Skip to main content

syncular_command/
lib.rs

1//! # syncular-command — one JSON command surface over the Rust client core
2//!
3//! The command router the conformance shim proved (JSON in, JSON out, bytes
4//! as `{"$bytes": hex}`) factored into a transport-agnostic module so BOTH
5//! the stdio conformance shim AND the FFI native core dispatch through the
6//! same code. That keeps a single command surface, conformance-locked via
7//! the shim: whatever the shim exercises, the FFI core inherits.
8//!
9//! The router is generic over the `Transport` seam. The shim binds it to a
10//! stdio host (transport inverted to the harness); the FFI crate binds it to
11//! a real native HTTP+WS transport. Everything host-specific — realtime
12//! notification draining, deferred requests, event queues — stays in each
13//! host; only the pure `method → result` dispatch (and its JSON parsing) is
14//! shared here.
15
16use serde_json::{json, Value};
17use ssp2::segment::{decode_rows_segment, encode_rows_segment};
18use ssp2::{
19    decode_message, encode_message, parse_control, render_message, render_rows_segment,
20    ControlMessage,
21};
22use syncular_client::previous_version::{PreviousVersionContextConfig, PreviousVersionReadSpec};
23use syncular_client::{
24    ClientError, ClientLimits, CommandEffects, CommitOutcomeQuery, LocalDataPurgeInput,
25    LocalDataRebootstrapInput, Mutation, QueryOwner, QueryReadFailure, RealtimePolicy,
26    ResolveCommitOutcomeInput, SyncClient, Transport, TransportError, UnitScopes, WindowBase,
27    WindowCoverage, LOCAL_AUTHORITY_UNCONFIGURED_CODE,
28};
29
30// -- bytes <-> {"$bytes": hex} (the driver-protocol byte envelope) ----------
31
32pub fn bytes_to_hex(bytes: &[u8]) -> String {
33    syncular_client::values::bytes_to_hex(bytes)
34}
35
36pub fn hex_to_bytes(hex: &str) -> Result<Vec<u8>, String> {
37    syncular_client::values::hex_to_bytes(hex)
38}
39
40pub fn bytes_value(bytes: &[u8]) -> Value {
41    Value::Object(serde_json::Map::from_iter([(
42        "$bytes".to_owned(),
43        Value::from(bytes_to_hex(bytes)),
44    )]))
45}
46
47pub fn value_bytes(value: Option<&Value>) -> Result<Vec<u8>, String> {
48    let hex = value
49        .and_then(|v| v.get("$bytes"))
50        .and_then(Value::as_str)
51        .ok_or_else(|| "expected a {\"$bytes\": hex} value".to_owned())?;
52    hex_to_bytes(hex)
53}
54
55/// The structured failure the driver protocol carries in an `error`. `details`
56/// and `retryable` carry the typed mutation fields to the host; non-mutation
57/// failures leave both at their defaults.
58#[derive(Debug, Clone)]
59pub struct CommandError {
60    pub code: String,
61    pub message: String,
62    pub details: Option<Value>,
63    pub retryable: bool,
64}
65
66impl CommandError {
67    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
68        Self {
69            code: code.into(),
70            message: message.into(),
71            details: None,
72            retryable: false,
73        }
74    }
75
76    /// Consume a structured client authoring failure without re-parsing text.
77    pub fn from_client(error: ClientError) -> Self {
78        Self {
79            code: error.code,
80            message: error.message,
81            details: error.details,
82            retryable: error.retryable,
83        }
84    }
85}
86
87impl From<(String, String)> for CommandError {
88    fn from((code, message): (String, String)) -> Self {
89        Self {
90            code,
91            message,
92            details: None,
93            retryable: false,
94        }
95    }
96}
97
98/// Parsed side effects of a `create` command that the host must apply to its
99/// own transport/clock (the router stays transport-agnostic). The client is
100/// already installed into the `Option<SyncClient>` slot by `dispatch`.
101#[derive(Debug, Default, Clone)]
102pub struct CreateEffects {
103    /// §5.4 capability the harness/host announced for its endpoints — the
104    /// host sets its transport's `supports_url_fetch` accordingly.
105    pub signed_urls: bool,
106    /// True while a security preflight is pending: a preflighted client was
107    /// installed (or entered preflight, or was shut down mid-preflight) and
108    /// `activateSecurity` has yet to complete. `dispatch` maintains this so a
109    /// replacement `create` without the `securityPreflight` flag is refused
110    /// across `shutdown`, where the client slot is empty, on a host that reuses
111    /// one `CreateEffects` across creates (the Tauri plugin, the conformance
112    /// shim, the bench harness).
113    ///
114    /// A host that allocates a fresh `CreateEffects` per create — the React
115    /// Native native module rebuilds its FFI handle on every `create` — starts
116    /// each create with this flag clear. For those hosts the persisted marker
117    /// in the client core carries the gate: a file-backed replica reopens in
118    /// preflight, and the `create` path refuses a plain re-create against it.
119    /// This in-memory flag covers the same-handle case where no file persists
120    /// the marker.
121    pub security_preflight_pending: bool,
122}
123
124/// §7.5: a read failure keeps its structured code, static message, SQLite
125/// details, and retryability across the command boundary.
126fn read_command_error(failure: QueryReadFailure) -> CommandError {
127    let details = failure.details();
128    let retryable = failure.retryable();
129    CommandError {
130        code: failure.code.unwrap_or("client.failed").to_owned(),
131        message: failure.message,
132        details,
133        retryable,
134    }
135}
136
137/// The code identity follows the client core's own rule
138/// (`ClientError::from`), so a colon-less `sync.unknown_table` keeps its code.
139/// The command boundary keeps the full rendered message.
140fn client_err(message: String) -> CommandError {
141    let code = ClientError::from(message.clone()).code;
142    let retryable = code == "client.storage_busy";
143    CommandError {
144        code,
145        message,
146        details: None,
147        retryable,
148    }
149}
150
151/// An optional command field. Absent or `null` keeps the caller's default; a
152/// present value `read` does not accept is `sync.invalid_request`, never a
153/// silent default.
154fn optional<'a, T>(
155    value: Option<&'a Value>,
156    field: &str,
157    read: impl FnOnce(&'a Value) -> Option<T>,
158) -> Result<Option<T>, String> {
159    match value {
160        None | Some(Value::Null) => Ok(None),
161        Some(value) => read(value)
162            .map(Some)
163            .ok_or_else(|| format!("sync.invalid_request: {field} has the wrong type")),
164    }
165}
166
167/// A transport failure keeps its code and structured details across the
168/// command boundary (`sync.attach_rejected` and its `details.reason`).
169fn transport_command_error(error: TransportError) -> CommandError {
170    CommandError {
171        code: error.code,
172        message: error.message,
173        details: error.details,
174        retryable: false,
175    }
176}
177
178fn need_client(client: &mut Option<SyncClient>) -> Result<&mut SyncClient, CommandError> {
179    client
180        .as_mut()
181        .ok_or_else(|| client_err("no client instance created".to_owned()))
182}
183
184/// RFC 0005 D8: parse the host's `previousVersionContext` config with the
185/// TS keys and defaults: `enabled` (default false), `maxBytes` 8 MiB,
186/// `maxRows` 20000, `maxTables` 32, `maxRowBytes` 1 MiB, `maxAgeMs` 24h.
187/// Invalid values fail the request loudly rather than silently defaulting.
188pub fn parse_previous_version_context(
189    value: Option<&Value>,
190) -> Result<Option<PreviousVersionContextConfig>, CommandError> {
191    let Some(value) = value else {
192        return Ok(None);
193    };
194    let object = value.as_object().ok_or_else(|| {
195        client_err("sync.invalid_request: previousVersionContext must be an object".to_owned())
196    })?;
197    let enabled = match object.get("enabled") {
198        None => false,
199        Some(Value::Bool(enabled)) => *enabled,
200        Some(_) => {
201            return Err(client_err(
202                "sync.invalid_request: previousVersionContext.enabled must be a boolean".to_owned(),
203            ))
204        }
205    };
206    let mut config = PreviousVersionContextConfig {
207        enabled,
208        ..PreviousVersionContextConfig::default()
209    };
210    for (key, slot) in [
211        ("maxBytes", &mut config.max_bytes),
212        ("maxRows", &mut config.max_rows),
213        ("maxTables", &mut config.max_tables),
214        ("maxRowBytes", &mut config.max_row_bytes),
215        ("maxAgeMs", &mut config.max_age_ms),
216    ] {
217        if let Some(raw) = object.get(key) {
218            *slot = raw.as_i64().ok_or_else(|| {
219                client_err(format!(
220                    "sync.invalid_request: previousVersionContext.{key} must be a positive safe integer"
221                ))
222            })?;
223        }
224    }
225    config.validate().map_err(client_err)?;
226    Ok(Some(config))
227}
228
229/// RFC 0005 D7: `previousVersionSnapshot` params — `{table, rowIds?, limit?}`.
230fn parse_previous_version_snapshot_spec(
231    params: &Value,
232) -> Result<PreviousVersionReadSpec, CommandError> {
233    let table = params.get("table").and_then(Value::as_str).ok_or_else(|| {
234        client_err("sync.invalid_request: previousVersionSnapshot missing table".to_owned())
235    })?;
236    let row_ids = match params.get("rowIds") {
237        None | Some(Value::Null) => Vec::new(),
238        Some(Value::Array(ids)) => ids
239            .iter()
240            .map(|id| match id {
241                Value::String(id) => Ok(id.clone()),
242                Value::Number(number) => Ok(number.to_string()),
243                Value::Bool(boolean) => Ok(boolean.to_string()),
244                _ => Err(client_err(
245                    "sync.invalid_request: previousVersionSnapshot rowIds must be strings"
246                        .to_owned(),
247                )),
248            })
249            .collect::<Result<Vec<_>, _>>()?,
250        Some(_) => {
251            return Err(client_err(
252                "sync.invalid_request: previousVersionSnapshot rowIds must be an array".to_owned(),
253            ))
254        }
255    };
256    let limit = match params.get("limit") {
257        None | Some(Value::Null) => None,
258        Some(value) => Some(value.as_i64().ok_or_else(|| {
259            client_err(
260                "sync.invalid_request: previousVersionSnapshot limit must be a positive number"
261                    .to_owned(),
262            )
263        })?),
264    };
265    Ok(PreviousVersionReadSpec {
266        table: table.to_owned(),
267        row_ids,
268        limit,
269    })
270}
271
272pub fn parse_limits(value: Option<&Value>) -> Result<ClientLimits, CommandError> {
273    let mut limits = ClientLimits::default();
274    let Some(object) = optional(value, "limits", Value::as_object).map_err(client_err)? else {
275        return Ok(limits);
276    };
277    let i32_field = |key: &str| {
278        optional(object.get(key), key, |v| {
279            v.as_i64().and_then(|n| i32::try_from(n).ok())
280        })
281        .map_err(client_err)
282    };
283    limits.limit_commits = i32_field("limitCommits")?;
284    limits.limit_snapshot_rows = i32_field("limitSnapshotRows")?;
285    limits.max_snapshot_pages = i32_field("maxSnapshotPages")?;
286    limits.accept = optional(object.get("accept"), "limits.accept", |v| {
287        v.as_u64().and_then(|n| u8::try_from(n).ok())
288    })
289    .map_err(client_err)?;
290    limits.blob_cache_max_bytes = optional(
291        object.get("blobCacheMaxBytes"),
292        "limits.blobCacheMaxBytes",
293        Value::as_i64,
294    )
295    .map_err(client_err)?;
296    limits.outcome_retention_max_entries = optional(
297        object.get("outcomeRetentionMaxEntries"),
298        "limits.outcomeRetentionMaxEntries",
299        |v| v.as_u64().and_then(|n| usize::try_from(n).ok()),
300    )
301    .map_err(client_err)?;
302    limits.max_push_commits_per_request = parse_push_limit(object, "maxPushCommitsPerRequest")?;
303    limits.max_push_operations_per_request =
304        parse_push_limit(object, "maxPushOperationsPerRequest")?;
305    limits.max_push_request_bytes = parse_push_limit(object, "maxPushRequestBytes")?;
306    Ok(limits)
307}
308
309/// §7.1: a configured push limit is a positive integer. Null or absent uses
310/// the default for that limit; invalid values fail with a structured error.
311fn parse_push_limit(
312    object: &serde_json::Map<String, Value>,
313    key: &str,
314) -> Result<Option<usize>, CommandError> {
315    match object.get(key) {
316        None | Some(Value::Null) => Ok(None),
317        Some(value) => value
318            .as_u64()
319            .and_then(|n| usize::try_from(n).ok())
320            .filter(|n| *n >= 1 && *n <= u32::MAX as usize)
321            .map(Some)
322            .ok_or_else(|| CommandError {
323                code: "sync.invalid_request".to_owned(),
324                message: "push limit must be an integer in 1..=4294967295".to_owned(),
325                details: Some(serde_json::json!({ "limit": key })),
326                retryable: false,
327            }),
328    }
329}
330
331/// §8.8: parse the `realtimePolicy` create param. Absent ⇒ `optional`.
332fn parse_realtime_policy(value: Option<&Value>) -> Result<RealtimePolicy, CommandError> {
333    match value {
334        None => Ok(RealtimePolicy::Optional),
335        Some(Value::String(text)) => match text.as_str() {
336            "required" => Ok(RealtimePolicy::Required),
337            "optional" => Ok(RealtimePolicy::Optional),
338            "off" => Ok(RealtimePolicy::Off),
339            other => Err(client_err(format!(
340                "sync.invalid_request: realtimePolicy must be 'required', 'optional', or 'off', got {other:?}"
341            ))),
342        },
343        Some(_) => Err(client_err(
344            "sync.invalid_request: realtimePolicy must be a string".to_owned(),
345        )),
346    }
347}
348
349/// §5.11: parse the `encryption` config into the client's portable keyring.
350/// Shape: `{ keys: { "<keyId>": {"$bytes": "<hex>"} },
351/// keyIdColumns: { "<table>": "<column>" } }`. Keys are 32 bytes.
352pub fn parse_encryption(
353    value: &Value,
354) -> Result<syncular_client::values::EncryptionConfig, String> {
355    let mut config = syncular_client::values::EncryptionConfig::default();
356    let Some(keys) = optional(value.get("keys"), "encryption.keys", Value::as_object)? else {
357        return Ok(config);
358    };
359    for (key_id, key_val) in keys {
360        let bytes =
361            value_bytes(Some(key_val)).map_err(|e| format!("encryption key {key_id:?}: {e}"))?;
362        if bytes.len() != 32 {
363            return Err(format!(
364                "encryption key {key_id:?} must be 32 bytes, got {}",
365                bytes.len()
366            ));
367        }
368        config.keys.insert(key_id.clone(), bytes);
369    }
370    if let Some(columns) = value.get("keyIdColumns") {
371        let columns = columns
372            .as_object()
373            .ok_or_else(|| "encryption keyIdColumns must be an object".to_owned())?;
374        for (table, column) in columns {
375            let column = column.as_str().ok_or_else(|| {
376                format!("encryption keyIdColumns entry for {table:?} must be a string")
377            })?;
378            if column.is_empty() {
379                return Err(format!(
380                    "encryption keyIdColumns entry for {table:?} must not be empty"
381                ));
382            }
383            config
384                .key_id_columns
385                .insert(table.clone(), column.to_owned());
386        }
387    }
388    Ok(config)
389}
390
391/// Parse an `activateSecurity` (or rotation) `headers` param: an object of
392/// string values, replacing the transport's FULL header set.
393/// The router validates the shape at the shared chokepoint; each host applies
394/// the parsed set to its own transport (the router stays transport-agnostic).
395pub fn parse_headers(value: &Value) -> Result<Vec<(String, String)>, String> {
396    let object = value.as_object().ok_or_else(|| {
397        "sync.invalid_request: headers must be an object of string values".to_owned()
398    })?;
399    let mut headers = Vec::with_capacity(object.len());
400    for (name, value) in object {
401        let value = value
402            .as_str()
403            .ok_or_else(|| format!("sync.invalid_request: header {name:?} must be a string"))?;
404        headers.push((name.clone(), value.to_owned()));
405    }
406    Ok(headers)
407}
408
409pub fn parse_mutations(value: Option<&Value>) -> Result<Vec<Mutation>, String> {
410    let list = value
411        .and_then(Value::as_array)
412        .ok_or_else(|| "mutations must be a list".to_owned())?;
413    let mut out = Vec::with_capacity(list.len());
414    for entry in list {
415        let op = entry
416            .get("op")
417            .and_then(Value::as_str)
418            .ok_or_else(|| "mutation missing op".to_owned())?;
419        let table = entry
420            .get("table")
421            .and_then(Value::as_str)
422            .ok_or_else(|| "mutation missing table".to_owned())?
423            .to_owned();
424        let base_version = optional(entry.get("baseVersion"), "baseVersion", Value::as_i64)?;
425        match op {
426            "upsert" | "patch" => {
427                let mut values = entry
428                    .get("values")
429                    .and_then(Value::as_object)
430                    .cloned()
431                    .ok_or_else(|| "upsert missing values".to_owned())?;
432                decode_bigint_members(&mut values)?;
433                out.push(if op == "patch" {
434                    Mutation::Patch {
435                        table,
436                        values,
437                        base_version,
438                    }
439                } else {
440                    Mutation::Upsert {
441                        table,
442                        values,
443                        base_version,
444                    }
445                });
446            }
447            "delete" => {
448                let row_id = entry
449                    .get("rowId")
450                    .and_then(Value::as_str)
451                    .ok_or_else(|| "delete missing rowId".to_owned())?
452                    .to_owned();
453                out.push(Mutation::Delete {
454                    table,
455                    row_id,
456                    base_version,
457                });
458            }
459            other => return Err(format!("unknown mutation op {other:?}")),
460        }
461    }
462    Ok(out)
463}
464
465fn decode_bigint_members(values: &mut serde_json::Map<String, Value>) -> Result<(), String> {
466    for value in values.values_mut() {
467        let Some(decimal) = value.get("$bigint").and_then(Value::as_str) else {
468            continue;
469        };
470        let integer = decimal
471            .parse::<i64>()
472            .map_err(|_| format!("bigint value {decimal:?} is outside SQLite's i64 range"))?;
473        *value = Value::from(integer);
474    }
475    Ok(())
476}
477
478/// §4.1: parse a unit scope map `{variable: value}`; absent fails.
479fn unit_scopes(value: Option<&Value>) -> Result<UnitScopes, String> {
480    serde_json::from_value(value.cloned().unwrap_or(Value::Null)).map_err(|_| {
481        "sync.invalid_request: a unit scope map is an object of string values".to_owned()
482    })
483}
484
485/// §4.8: parse a window base descriptor `{ variable, fixedScopes? }` from a
486/// command's `base` param.
487fn window_base_from_params(value: Option<&Value>) -> Result<WindowBase, String> {
488    let object = value
489        .and_then(Value::as_object)
490        .ok_or_else(|| "sync.invalid_request: window base must be an object".to_owned())?;
491    let variable = object
492        .get("variable")
493        .and_then(Value::as_str)
494        .ok_or_else(|| "sync.invalid_request: window base missing variable".to_owned())?
495        .to_owned();
496    Ok(WindowBase {
497        variable,
498        fixed_scopes: match object.get("fixedScopes") {
499            None | Some(Value::Null) => UnitScopes::new(),
500            scopes => unit_scopes(scopes)?,
501        },
502    })
503}
504
505/// §7.5: parse a `coverage` array of `{base, units}` entries. Absent or null is
506/// empty; a non-array, a malformed base, or non-string units are rejected
507/// explicitly instead of silently defaulting. Shared with the Tauri plugin's
508/// read sidecar.
509pub fn parse_window_coverage(value: Option<&Value>) -> Result<Vec<WindowCoverage>, String> {
510    let entries = match value {
511        None | Some(Value::Null) => return Ok(Vec::new()),
512        Some(Value::Array(entries)) => entries,
513        Some(_) => return Err("sync.invalid_request: coverage must be a list".to_owned()),
514    };
515    let mut coverage = Vec::with_capacity(entries.len());
516    for entry in entries {
517        let units = match entry.get("units") {
518            None | Some(Value::Null) => Vec::new(),
519            Some(Value::Array(values)) => values
520                .iter()
521                .map(|value| value.as_str().map(str::to_owned))
522                .collect::<Option<Vec<_>>>()
523                .ok_or_else(|| {
524                    "sync.invalid_request: coverage units must be a list of strings".to_owned()
525                })?,
526            Some(_) => {
527                return Err(
528                    "sync.invalid_request: coverage units must be a list of strings".to_owned(),
529                )
530            }
531        };
532        coverage.push(WindowCoverage {
533            base: window_base_from_params(entry.get("base"))?,
534            units,
535        });
536    }
537    Ok(coverage)
538}
539
540/// §7.5 owner: `{id, tables}`, both required when present. Shared by
541/// `querySnapshot` and `snapshotRead`.
542fn parse_query_owner<'a>(
543    params: &'a Value,
544    method: &str,
545) -> Result<Option<(&'a str, Vec<&'a str>)>, CommandError> {
546    match params.get("owner") {
547        None | Some(Value::Null) => Ok(None),
548        Some(value) => {
549            let id = value
550                .get("id")
551                .and_then(Value::as_str)
552                .filter(|id| !id.is_empty());
553            let tables = value
554                .get("tables")
555                .and_then(Value::as_array)
556                .and_then(|list| {
557                    list.iter()
558                        .map(Value::as_str)
559                        .collect::<Option<Vec<&str>>>()
560                });
561            match (id, tables) {
562                (Some(id), Some(tables)) => Ok(Some((id, tables))),
563                _ => Err(client_err(format!(
564                    "sync.invalid_request: {method} owner must be {{id: non-empty string, tables: string[]}}"
565                ))),
566            }
567        }
568    }
569}
570
571/// §7.5: parse a `units`/`commitIds` list. Absent or null is empty; a
572/// non-array or a non-string entry is rejected explicitly.
573fn snapshot_string_list(value: Option<&Value>) -> Result<Vec<String>, CommandError> {
574    match value {
575        None | Some(Value::Null) => Ok(Vec::new()),
576        Some(Value::Array(items)) => items
577            .iter()
578            .map(|item| item.as_str().map(str::to_owned))
579            .collect::<Option<Vec<String>>>()
580            .ok_or_else(|| {
581                client_err(
582                    "sync.invalid_request: snapshotRead list must contain strings".to_owned(),
583                )
584            }),
585        Some(_) => Err(client_err(
586            "sync.invalid_request: snapshotRead list must be a list of strings".to_owned(),
587        )),
588    }
589}
590
591/// §5.10.5: parse the common `(table, rowId, column, name)` target of a crdt
592/// command. `name` selects the shared type inside the doc (default `"text"`,
593/// matching the TS `YjsColumn.text()` default).
594#[cfg(feature = "crdt-yjs")]
595fn crdt_target(params: &Value) -> Result<(String, String, String, String), CommandError> {
596    let table = params
597        .get("table")
598        .and_then(Value::as_str)
599        .ok_or_else(|| client_err("crdt command missing table".to_owned()))?
600        .to_owned();
601    let row_id = params
602        .get("rowId")
603        .and_then(Value::as_str)
604        .ok_or_else(|| client_err("crdt command missing rowId".to_owned()))?
605        .to_owned();
606    let column = params
607        .get("column")
608        .and_then(Value::as_str)
609        .ok_or_else(|| client_err("crdt command missing column".to_owned()))?
610        .to_owned();
611    let name = optional(params.get("name"), "crdt name", Value::as_str)
612        .map_err(client_err)?
613        .unwrap_or("text")
614        .to_owned();
615    Ok((table, row_id, column, name))
616}
617
618/// Dispatch one command against the client instance over `transport`.
619///
620/// The `create` command installs a fresh `SyncClient` into `client` and
621/// returns its parsed `CreateEffects` in the `Ok` result via `effects`; every
622/// other command mutates the existing instance. Errors come back as the
623/// driver-protocol `(code, message)` pair.
624///
625/// Generic over `T: Transport` so the shim (host-inverted transport) and the
626/// FFI core (native HTTP+WS transport) share this exact router.
627pub fn dispatch<T: Transport>(
628    transport: &mut T,
629    client: &mut Option<SyncClient>,
630    effects: &mut CreateEffects,
631    method: &str,
632    params: &Value,
633) -> Result<Value, CommandError> {
634    if method == "create" {
635        // Fail-closed against a compromised webview re-issuing `create` (or
636        // `shutdown` + `create`) WITHOUT the securityPreflight flag to exit
637        // the gate: while a preflight is pending — on the live client, or
638        // carried in `effects` across a `shutdown` — a replacement create must
639        // itself request securityPreflight; the gate opens only through
640        // activateSecurity.
641        let requests_preflight = optional(
642            params.get("securityPreflight"),
643            "securityPreflight",
644            Value::as_bool,
645        )
646        .map_err(client_err)?
647        .unwrap_or(false);
648        let preflight_engaged = client.as_ref().map_or(
649            effects.security_preflight_pending,
650            SyncClient::security_preflight,
651        );
652        if preflight_engaged && !requests_preflight {
653            return Err(CommandError::new(
654                syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
655                "the local replica is in security preflight; a replacement create must itself request securityPreflight, and protected data opens only after activateSecurity",
656            ));
657        }
658    } else {
659        let allowed_during_preflight = matches!(
660            method,
661            "authoritySnapshot"
662                | "securityLifecycle"
663                | "beginSecurityPreflight"
664                | "activateSecurity"
665                | "setTransportEnabled"
666                | "purgeLocalData"
667                | "previousVersionDiscard"
668                | "localRevision"
669                | "statusSnapshot"
670                | "localAuthorityState"
671                | "drainRealtime"
672                | "shutdown"
673        );
674        if client
675            .as_ref()
676            .is_some_and(|running| running.security_preflight())
677            && !allowed_during_preflight
678        {
679            return Err(CommandError::new(
680                syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
681                "the local replica is in security preflight; complete quarantine checks and call activateSecurity before accessing protected data",
682            ));
683        }
684    }
685    let mut result = match method {
686        "create" => {
687            let client_id = optional(params.get("clientId"), "clientId", Value::as_str)
688                .map_err(client_err)?
689                .map(str::to_owned);
690            let db_path =
691                optional(params.get("dbPath"), "dbPath", Value::as_str).map_err(client_err)?;
692            let schema = params
693                .get("schema")
694                .ok_or_else(|| client_err("create missing schema".to_owned()))?;
695            let limits = parse_limits(params.get("limits"))?;
696            // RFC 0005 D8: the feature config rides the top-level key the TS
697            // client uses; the Rust core carries it on `ClientLimits` so it is
698            // resolved before the opening schema reset runs.
699            let previous_version_context =
700                parse_previous_version_context(params.get("previousVersionContext"))?;
701            let mut limits = limits;
702            limits.previous_version_context = previous_version_context;
703            if let Some(reads) = params.get("authorityReads") {
704                limits.authority_reads = serde_json::from_value(reads.clone()).map_err(|_| {
705                    client_err(
706                        "client.authority_read_forbidden: invalid authority declaration".into(),
707                    )
708                })?;
709            }
710            // §12: a host-configured local authority opens with the client's
711            // schema before the client, as the browser worker opens it.
712            transport
713                .open_local_authority(schema, db_path)
714                .map_err(transport_command_error)?;
715            // §native: a `dbPath` installs a file-backed rusqlite connection so
716            // native hosts (Tauri plugin, FFI file variant) persist across
717            // restarts; absent it, the default in-memory core (the shim's mode).
718            let mut instance = match db_path {
719                Some(path) => SyncClient::open_path_with_identity(client_id, schema, limits, path)
720                    .map_err(client_err)?,
721                None => {
722                    SyncClient::new_with_identity(client_id, schema, limits).map_err(client_err)?
723                }
724            };
725            instance
726                .set_retain_failed_commits(
727                    optional(
728                        params.get("retainFailedCommits"),
729                        "retainFailedCommits",
730                        Value::as_bool,
731                    )
732                    .map_err(client_err)?
733                    .unwrap_or(false),
734                )
735                .map_err(client_err)?;
736            // §8.8: the realtime policy rides the create params; absent ⇒
737            // `optional` (today's socket-or-HTTP behavior).
738            let realtime_policy = parse_realtime_policy(params.get("realtimePolicy"))?;
739            instance
740                .set_realtime_policy(realtime_policy)
741                .map_err(client_err)?;
742            // Harness clock pin (§5.4 expiry runs on the virtual clock).
743            if let Some(now_ms) =
744                optional(params.get("nowMs"), "nowMs", Value::as_i64).map_err(client_err)?
745            {
746                instance.set_now_ms(now_ms);
747            }
748            // §5.4 capability of the host endpoint set (accept bit 3) — the
749            // host applies it to its own transport.
750            effects.signed_urls = optional(params.get("signedUrls"), "signedUrls", Value::as_bool)
751                .map_err(client_err)?
752                .unwrap_or(false);
753            // §5.11: install client-side encryption keys. Shape:
754            // { encryption: { keys: { "<keyId>": {"$bytes": "<hex>"} },
755            //                 keyIdColumns: { "<table>": "<column>" } } }.
756            let security_preflight = optional(
757                params.get("securityPreflight"),
758                "securityPreflight",
759                Value::as_bool,
760            )
761            .map_err(client_err)?
762            .unwrap_or(false);
763            // A file-backed replica reopens in preflight when its persisted
764            // quarantine marker is set (client core restores it). Refuse a plain
765            // re-create so a rebuilt host handle — the React Native native module
766            // tears its FFI handle down on every create — cannot downgrade a
767            // quarantined replica to active. A create that itself requests
768            // securityPreflight, or an activated replica whose marker cleared,
769            // proceeds.
770            if instance.security_preflight() && !security_preflight {
771                return Err(CommandError::new(
772                    syncular_client::SECURITY_PREFLIGHT_REQUIRED_CODE,
773                    "the local replica is in security preflight; a replacement create must itself request securityPreflight, and protected data opens only after activateSecurity",
774                ));
775            }
776            if security_preflight && params.get("encryption").is_some() {
777                return Err(client_err(
778                    "sync.invalid_request: securityPreflight and encryption are mutually exclusive; install keys with activateSecurity after preflight"
779                        .to_owned(),
780                ));
781            }
782            if let Some(enc) = params.get("encryption") {
783                let config = parse_encryption(enc).map_err(client_err)?;
784                instance.set_encryption(config);
785            }
786            if security_preflight {
787                instance.begin_security_preflight().map_err(client_err)?;
788            }
789            if let Some(enabled) = params.get("transportEnabled") {
790                let enabled = enabled.as_bool().ok_or_else(|| {
791                    client_err("sync.invalid_request: transportEnabled must be a boolean".into())
792                })?;
793                instance.set_transport_enabled(transport, enabled);
794            }
795            effects.security_preflight_pending = security_preflight;
796            *client = Some(instance);
797            Ok(json!({}))
798        }
799        "securityLifecycle" => Ok(json!({
800            "state": need_client(client)?.security_lifecycle()
801        })),
802        "beginSecurityPreflight" => {
803            let running = need_client(client)?;
804            running.disconnect_realtime(transport);
805            running.begin_security_preflight().map_err(client_err)?;
806            effects.security_preflight_pending = true;
807            Ok(json!({}))
808        }
809        "authoritySnapshot" => {
810            if !params.as_object().is_some_and(|p| p.is_empty()) {
811                return Err(client_err(
812                    "client.authority_read_forbidden: authoritySnapshot accepts no arguments"
813                        .into(),
814                ));
815            }
816            client
817                .as_ref()
818                .ok_or_else(|| client_err("client.closed: no authority client is open".into()))?
819                .authority_snapshot()
820                .map_err(client_err)
821        }
822        "activateSecurity" => {
823            let encryption = match params.get("encryption") {
824                Some(value) => parse_encryption(value).map_err(client_err)?,
825                None => syncular_client::values::EncryptionConfig::default(),
826            };
827            // Optional fresh transport headers ride the activation atomically,
828            // so a preflight that outlives the boot token starts its first
829            // sync round with valid credentials. Validated here at the shared
830            // chokepoint (invalid input keeps the gate closed); the host
831            // applies the parsed set to its own transport.
832            if let Some(headers) = params.get("headers") {
833                parse_headers(headers).map_err(client_err)?;
834            }
835            need_client(client)?
836                .activate_security(encryption)
837                .map_err(client_err)?;
838            effects.security_preflight_pending = false;
839            Ok(json!({}))
840        }
841        "setTransportEnabled" => {
842            let enabled = params
843                .get("enabled")
844                .and_then(Value::as_bool)
845                .ok_or_else(|| {
846                    client_err(
847                        "sync.invalid_request: setTransportEnabled.enabled must be a boolean"
848                            .into(),
849                    )
850                })?;
851            need_client(client)?.set_transport_enabled(transport, enabled);
852            Ok(json!({}))
853        }
854        "setHeaders" => {
855            let headers = params
856                .get("headers")
857                .ok_or_else(|| client_err("setHeaders missing headers".to_owned()))?;
858            parse_headers(headers).map_err(client_err)?;
859            Ok(json!({}))
860        }
861        "shutdown" => {
862            if let Some(running) = client.as_mut() {
863                // Capture the gate state BEFORE the shutdown barrier flips the
864                // client into preflight: an unactivated preflight stays
865                // pending across the shutdown, while an activated client may
866                // be recreated plainly afterwards.
867                effects.security_preflight_pending = running.security_preflight();
868                running.disconnect_realtime(transport);
869                // Teardown barrier only: an activated client that shuts down
870                // cleanly must not leave a durable quarantine mark, or its next
871                // plain create would be refused forever.
872                running.seal_security_on_teardown();
873            }
874            *client = None;
875            Ok(json!({}))
876        }
877        "subscribe" => {
878            let scopes = unit_scopes(params.get("scopes")).map_err(client_err)?;
879            let id = need_client(client)?.subscribe(scopes).map_err(client_err)?;
880            Ok(json!({ "id": id }))
881        }
882        "subscribeMany" => {
883            let units = params
884                .get("units")
885                .and_then(Value::as_array)
886                .ok_or_else(|| {
887                    client_err(
888                        "sync.invalid_request: subscribeMany units must be a list".to_owned(),
889                    )
890                })?
891                .iter()
892                .map(|scopes| unit_scopes(Some(scopes)))
893                .collect::<Result<Vec<_>, _>>()
894                .map_err(client_err)?;
895            let ids = need_client(client)?
896                .subscribe_many(units)
897                .map_err(client_err)?;
898            Ok(json!({ "ids": ids }))
899        }
900        "unsubscribe" => {
901            let id = params
902                .get("id")
903                .and_then(Value::as_str)
904                .ok_or_else(|| client_err("unsubscribe missing id".to_owned()))?;
905            need_client(client)?.unsubscribe(id).map_err(client_err)?;
906            Ok(json!({}))
907        }
908        "setWindow" => {
909            let base = window_base_from_params(params.get("base")).map_err(client_err)?;
910            let units: Vec<String> = optional(params.get("units"), "setWindow units", |v| {
911                v.as_array()?
912                    .iter()
913                    .map(|unit| unit.as_str().map(str::to_owned))
914                    .collect()
915            })
916            .map_err(client_err)?
917            .unwrap_or_default();
918            let command_effects = need_client(client)?
919                .set_window(&base, &units)
920                .map_err(client_err)?;
921            Ok(json!({ "effects": command_effects }))
922        }
923        "windowState" => {
924            let base = window_base_from_params(params.get("base")).map_err(client_err)?;
925            let state = need_client(client)?
926                .window_state(&base)
927                .map_err(client_err)?;
928            Ok(json!({ "units": state.units, "pending": state.pending }))
929        }
930        "timeWindowSugar" => {
931            let created_at_ms = params
932                .get("createdAtMs")
933                .and_then(Value::as_i64)
934                .ok_or_else(|| client_err("timeWindowSugar missing createdAtMs".to_owned()))?;
935            let count = params
936                .get("count")
937                .and_then(Value::as_u64)
938                .and_then(|value| usize::try_from(value).ok())
939                .ok_or_else(|| client_err("timeWindowSugar missing count".to_owned()))?;
940            let now_ms = params
941                .get("nowMs")
942                .and_then(Value::as_i64)
943                .ok_or_else(|| client_err("timeWindowSugar missing nowMs".to_owned()))?;
944            if params.get("unit").and_then(Value::as_str) != Some("month") {
945                return Err(client_err(
946                    "sync.invalid_request: timeWindowSugar requires the month unit".to_owned(),
947                ));
948            }
949            let unit = syncular_client::TimeBucketUnit::Month;
950            Ok(json!({
951                "bucket": syncular_client::creation_time_bucket(created_at_ms, unit)
952                    .map_err(client_err)?,
953                "units": syncular_client::last(count, unit, now_ms).map_err(client_err)?,
954            }))
955        }
956        "mutate" => {
957            let mutations = parse_mutations(params.get("mutations")).map_err(client_err)?;
958            // §7.1: an optional caller-supplied commit ID.
959            let client_commit_id = match params.get("clientCommitId") {
960                None | Some(Value::Null) => None,
961                Some(Value::String(id)) => Some(id.clone()),
962                Some(_) => {
963                    return Err(client_err(
964                        "sync.invalid_request: clientCommitId must be a string".to_owned(),
965                    ))
966                }
967            };
968            let id = need_client(client)?
969                .mutate_with_commit_id(mutations, client_commit_id)
970                .map_err(CommandError::from_client)?;
971            Ok(json!({
972                "clientCommitId": id,
973                "effects": CommandEffects::interactive()
974            }))
975        }
976        "patch" => {
977            let table = params
978                .get("table")
979                .and_then(Value::as_str)
980                .ok_or_else(|| client_err("patch missing table".to_owned()))?;
981            let row_id = params
982                .get("rowId")
983                .and_then(Value::as_str)
984                .ok_or_else(|| client_err("patch missing rowId".to_owned()))?;
985            let mut partial = params
986                .get("partial")
987                .and_then(Value::as_object)
988                .cloned()
989                .ok_or_else(|| client_err("patch missing partial object".to_owned()))?;
990            decode_bigint_members(&mut partial).map_err(client_err)?;
991            let base_version = optional(params.get("baseVersion"), "baseVersion", Value::as_i64)
992                .map_err(client_err)?;
993            let id = need_client(client)?
994                .patch(table, row_id, partial, base_version)
995                .map_err(CommandError::from_client)?;
996            Ok(json!({
997                "clientCommitId": id,
998                "effects": CommandEffects::interactive()
999            }))
1000        }
1001        "purgeLocalData" => {
1002            let input: LocalDataPurgeInput =
1003                serde_json::from_value(params.get("input").cloned().ok_or_else(|| {
1004                    client_err("sync.invalid_request: purgeLocalData missing input".to_owned())
1005                })?)
1006                .map_err(|error| {
1007                    client_err(format!(
1008                        "sync.invalid_request: invalid purgeLocalData input: {error}"
1009                    ))
1010                })?;
1011            let result = need_client(client)?
1012                .purge_local_data(&input)
1013                .map_err(client_err)?;
1014            serde_json::to_value(result).map_err(|error| client_err(error.to_string()))
1015        }
1016        "rebootstrapLocalData" => {
1017            let input: LocalDataRebootstrapInput =
1018                serde_json::from_value(params.get("input").cloned().ok_or_else(|| {
1019                    client_err(
1020                        "sync.invalid_request: rebootstrapLocalData missing input".to_owned(),
1021                    )
1022                })?)
1023                .map_err(|error| {
1024                    client_err(format!(
1025                        "sync.invalid_request: invalid rebootstrapLocalData input: {error}"
1026                    ))
1027                })?;
1028            let result = need_client(client)?
1029                .rebootstrap_local_data(&input)
1030                .map_err(client_err)?;
1031            Ok(json!({
1032                "alreadyApplied": result.already_applied,
1033                "retainedCommits": result.retained_commits,
1034                "resetSubscriptions": result.reset_subscriptions,
1035                "effects": if result.already_applied {
1036                    CommandEffects::none()
1037                } else {
1038                    CommandEffects::interactive()
1039                }
1040            }))
1041        }
1042        "sync" => {
1043            let outcome = need_client(client)?.sync(transport);
1044            Ok(outcome.to_json())
1045        }
1046        "resetClientId" | "reset_client_id" => {
1047            let client_id = need_client(client)?
1048                .reset_client_id(transport)
1049                .map_err(client_err)?;
1050            Ok(json!({ "clientId": client_id }))
1051        }
1052        "syncUntilIdle" => {
1053            let max_rounds = match params.get("maxRounds") {
1054                None | Some(Value::Null) => None,
1055                Some(value) => Some(
1056                    value
1057                        .as_u64()
1058                        .and_then(|n| u32::try_from(n).ok())
1059                        .filter(|n| *n >= 1)
1060                        .ok_or_else(|| {
1061                            client_err(
1062                                "sync.invalid_request: maxRounds must be a positive integer"
1063                                    .to_owned(),
1064                            )
1065                        })?,
1066                ),
1067            };
1068            let timeout_ms = match params.get("timeoutMs") {
1069                None | Some(Value::Null) => None,
1070                Some(value) => Some(value.as_u64().filter(|ms| *ms >= 1).ok_or_else(|| {
1071                    client_err(
1072                        "sync.invalid_request: timeoutMs must be a positive integer".to_owned(),
1073                    )
1074                })?),
1075            };
1076            let client = need_client(client)?;
1077            let outcome = match timeout_ms {
1078                Some(timeout_ms) => {
1079                    client.sync_until_idle_with_deadline(transport, max_rounds, Some(timeout_ms))
1080                }
1081                None => client.sync_until_idle(transport, max_rounds),
1082            };
1083            Ok(outcome.to_json())
1084        }
1085        "proveCurrentBase" => {
1086            let outcome = params
1087                .get("outcome")
1088                .and_then(Value::as_object)
1089                .ok_or_else(|| client_err("proveCurrentBase missing outcome".to_owned()))?;
1090            let id = outcome
1091                .get("clientCommitId")
1092                .and_then(Value::as_str)
1093                .ok_or_else(|| client_err("proveCurrentBase missing clientCommitId".to_owned()))?;
1094            let sequence = outcome
1095                .get("sequence")
1096                .and_then(Value::as_i64)
1097                .ok_or_else(|| client_err("proveCurrentBase missing sequence".to_owned()))?;
1098            let max_rounds = match params.get("maxRounds") {
1099                None | Some(Value::Null) => None,
1100                Some(value) => Some(
1101                    value
1102                        .as_u64()
1103                        .and_then(|n| u32::try_from(n).ok())
1104                        .filter(|n| *n >= 1)
1105                        .ok_or_else(|| {
1106                            client_err(
1107                                "sync.invalid_request: maxRounds must be a positive integer"
1108                                    .to_owned(),
1109                            )
1110                        })?,
1111                ),
1112            };
1113            Ok(json!(
1114                need_client(client)?.prove_current_base(transport, id, sequence, max_rounds)
1115            ))
1116        }
1117        "readRows" => {
1118            let table = params
1119                .get("table")
1120                .and_then(Value::as_str)
1121                .ok_or_else(|| client_err("readRows missing table".to_owned()))?;
1122            let rows = need_client(client)?.read_rows(table).map_err(client_err)?;
1123            Ok(json!({ "rows": rows }))
1124        }
1125        "query" => {
1126            // The React `useSyncQuery` live-query fast path: arbitrary read-only
1127            // SQL over the local visible tables/views. Params ride as the driver
1128            // value forms (bytes as `{"$bytes": hex}`); rows come back the same.
1129            let sql = params
1130                .get("sql")
1131                .and_then(Value::as_str)
1132                .ok_or_else(|| client_err("query missing sql".to_owned()))?;
1133            let bind = match params.get("params") {
1134                Some(Value::Array(list)) => list.as_slice(),
1135                None | Some(Value::Null) => &[],
1136                Some(_) => return Err(client_err("query params must be a list".to_owned())),
1137            };
1138            let rows = need_client(client)?.query(sql, bind).map_err(client_err)?;
1139            Ok(Value::Object(serde_json::Map::from_iter([(
1140                "rows".to_owned(),
1141                Value::Array(rows.into_iter().map(Value::Object).collect()),
1142            )])))
1143        }
1144        "querySnapshot" => {
1145            let sql = params
1146                .get("sql")
1147                .and_then(Value::as_str)
1148                .ok_or_else(|| client_err("querySnapshot missing sql".to_owned()))?;
1149            let bind = match params.get("params") {
1150                Some(Value::Array(list)) => list.as_slice(),
1151                None | Some(Value::Null) => &[],
1152                Some(_) => {
1153                    return Err(client_err("querySnapshot params must be a list".to_owned()))
1154                }
1155            };
1156            let coverage = parse_window_coverage(params.get("coverage")).map_err(client_err)?;
1157            let owner = parse_query_owner(params, "querySnapshot")?;
1158            let mut snapshot = need_client(client)?
1159                .query_snapshot(
1160                    sql,
1161                    bind,
1162                    &coverage,
1163                    owner.as_ref().map(|(id, tables)| QueryOwner { id, tables }),
1164                )
1165                .map_err(client_err)?;
1166            let rows = std::mem::take(&mut snapshot.rows);
1167            let mut result = serde_json::to_value(snapshot).expect("snapshot serializes");
1168            result["rows"] = Value::Array(rows.into_iter().map(Value::Object).collect());
1169            Ok(result)
1170        }
1171        "localRevision" => {
1172            // §7.5: the public revision read is fallible. An empty shared
1173            // snapshot read reports a corrupt marker instead of swallowing it
1174            // to zero. The internal infallible counter stays for bookkeeping.
1175            let read = need_client(client)?
1176                .snapshot_read(&syncular_client::SnapshotReadRequest::default(), None)
1177                .map_err(read_command_error)?;
1178            Ok(json!({ "revision": read.revision }))
1179        }
1180        "snapshotRead" => {
1181            let mut statement_sql: Vec<String> = Vec::new();
1182            let mut statement_params: Vec<Vec<Value>> = Vec::new();
1183            match params.get("statements") {
1184                None | Some(Value::Null) => {}
1185                Some(Value::Array(items)) => {
1186                    for item in items {
1187                        let Some(sql) = item.get("sql").and_then(Value::as_str) else {
1188                            return Err(client_err(
1189                                "sync.invalid_request: snapshotRead statements need a sql string"
1190                                    .to_owned(),
1191                            ));
1192                        };
1193                        let bind = match item.get("params") {
1194                            None | Some(Value::Null) => Vec::new(),
1195                            Some(Value::Array(values)) => values.clone(),
1196                            Some(_) => {
1197                                return Err(client_err(
1198                                    "sync.invalid_request: snapshotRead statement params must be a list"
1199                                        .to_owned(),
1200                                ))
1201                            }
1202                        };
1203                        statement_sql.push(sql.to_owned());
1204                        statement_params.push(bind);
1205                    }
1206                }
1207                Some(_) => {
1208                    return Err(client_err(
1209                        "sync.invalid_request: snapshotRead statements must be a list".to_owned(),
1210                    ))
1211                }
1212            }
1213            let units = snapshot_string_list(params.get("units"))?;
1214            let commit_ids = snapshot_string_list(params.get("commitIds"))?;
1215            let coverage = parse_window_coverage(params.get("coverage")).map_err(client_err)?;
1216            let owner = parse_query_owner(params, "snapshotRead")?;
1217            let statements: Vec<syncular_client::SnapshotStatement<'_>> = statement_sql
1218                .iter()
1219                .zip(&statement_params)
1220                .map(|(sql, params)| syncular_client::SnapshotStatement { sql, params })
1221                .collect();
1222            let read = need_client(client)?
1223                .snapshot_read(
1224                    &syncular_client::SnapshotReadRequest {
1225                        statements,
1226                        coverage: &coverage,
1227                        units,
1228                        commit_ids,
1229                    },
1230                    owner.as_ref().map(|(id, tables)| QueryOwner { id, tables }),
1231                )
1232                .map_err(read_command_error)?;
1233            serde_json::to_value(read).map_err(|error| client_err(error.to_string()))
1234        }
1235        "previousVersionSnapshot" | "previous_version_snapshot" => {
1236            let spec = parse_previous_version_snapshot_spec(params)?;
1237            let snapshot = need_client(client)?
1238                .previous_version_snapshot(&spec)
1239                .map_err(client_err)?;
1240            serde_json::to_value(snapshot).map_err(|error| client_err(error.to_string()))
1241        }
1242        "previousVersionAudit" | "previous_version_audit" => Ok(
1243            match need_client(client)?
1244                .previous_version_audit()
1245                .map_err(client_err)?
1246            {
1247                Some(audit) => {
1248                    serde_json::to_value(audit).map_err(|error| client_err(error.to_string()))?
1249                }
1250                None => Value::Null,
1251            },
1252        ),
1253        "previousVersionDiscard" | "previous_version_discard" => {
1254            let outcome = need_client(client)?
1255                .previous_version_discard()
1256                .map_err(client_err)?;
1257            Ok(json!({
1258                "present": outcome.present,
1259                "discarded": outcome.discarded,
1260            }))
1261        }
1262        "statusSnapshot" => Ok(serde_json::to_value(need_client(client)?.status_snapshot())
1263            .expect("status serializes")),
1264        "diagnosticsSnapshot" => {
1265            let snapshot = need_client(client)?
1266                .diagnostics_snapshot()
1267                .map_err(client_err)?;
1268            Ok(serde_json::to_value(snapshot).expect("diagnostics serialize"))
1269        }
1270        // Conformance/debug drains. Production hosts normally drain these
1271        // immediately after every command, but exposing the exact core output
1272        // here lets both client implementations consume one observation
1273        // vector catalog without bridge inference.
1274        "progressSnapshot" => Ok(
1275            serde_json::to_value(need_client(client)?.progress().snapshot())
1276                .expect("progress JSON"),
1277        ),
1278        "drainChangeBatches" => Ok(json!({
1279            "batches": need_client(client)?.drain_change_batches()
1280        })),
1281        "drainSyncIntents" => Ok(json!({
1282            "intents": need_client(client)?.drain_sync_intents()
1283        })),
1284        // -- §5.10.5 native CRDT (the `crdt-yjs` feature) -----------------------
1285        // Thin forwards to the client core's yrs helpers. The command surface
1286        // stays present-but-unavailable in a lean build: without the feature
1287        // these fail loudly (`client.crdt_unavailable`) rather than being an
1288        // unknown method, so a wrapper's typed method gives a clear error.
1289        #[cfg(feature = "crdt-yjs")]
1290        "crdtText" => {
1291            let (table, row_id, column, name) = crdt_target(params)?;
1292            let text = need_client(client)?
1293                .crdt_text(&table, &row_id, &column, &name)
1294                .map_err(client_err)?;
1295            Ok(json!({ "text": text }))
1296        }
1297        #[cfg(feature = "crdt-yjs")]
1298        "crdtInsertText" => {
1299            let (table, row_id, column, name) = crdt_target(params)?;
1300            let index = params
1301                .get("index")
1302                .and_then(Value::as_u64)
1303                .and_then(|n| u32::try_from(n).ok())
1304                .ok_or_else(|| {
1305                    client_err(
1306                        "sync.invalid_request: crdtInsertText index must be a u32".to_owned(),
1307                    )
1308                })?;
1309            let value = params
1310                .get("value")
1311                .and_then(Value::as_str)
1312                .ok_or_else(|| client_err("crdtInsertText missing value".to_owned()))?;
1313            let id = need_client(client)?
1314                .crdt_insert_text(&table, &row_id, &column, &name, index, value)
1315                .map_err(CommandError::from_client)?;
1316            Ok(json!({ "clientCommitId": id }))
1317        }
1318        #[cfg(feature = "crdt-yjs")]
1319        "crdtDeleteText" => {
1320            let (table, row_id, column, name) = crdt_target(params)?;
1321            let index = params
1322                .get("index")
1323                .and_then(Value::as_u64)
1324                .and_then(|n| u32::try_from(n).ok())
1325                .ok_or_else(|| {
1326                    client_err(
1327                        "sync.invalid_request: crdtDeleteText index must be a u32".to_owned(),
1328                    )
1329                })?;
1330            let len = params
1331                .get("len")
1332                .and_then(Value::as_u64)
1333                .and_then(|n| u32::try_from(n).ok())
1334                .ok_or_else(|| {
1335                    client_err("sync.invalid_request: crdtDeleteText len must be a u32".to_owned())
1336                })?;
1337            let id = need_client(client)?
1338                .crdt_delete_text(&table, &row_id, &column, &name, index, len)
1339                .map_err(CommandError::from_client)?;
1340            Ok(json!({ "clientCommitId": id }))
1341        }
1342        #[cfg(feature = "crdt-yjs")]
1343        "crdtApplyUpdate" => {
1344            let (table, row_id, column, _name) = crdt_target(params)?;
1345            let update = value_bytes(params.get("update")).map_err(client_err)?;
1346            let id = need_client(client)?
1347                .crdt_apply_update(&table, &row_id, &column, &update)
1348                .map_err(CommandError::from_client)?;
1349            Ok(json!({ "clientCommitId": id }))
1350        }
1351        #[cfg(not(feature = "crdt-yjs"))]
1352        "crdtText" | "crdtInsertText" | "crdtDeleteText" | "crdtApplyUpdate" => {
1353            Err(CommandError::new(
1354                "client.crdt_unavailable",
1355                "native CRDT support requires the `crdt-yjs` feature (§5.10.5)",
1356            ))
1357        }
1358
1359        "uploadBlob" => {
1360            let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1361            let media_type = optional(params.get("mediaType"), "mediaType", Value::as_str)
1362                .map_err(client_err)?
1363                .map(str::to_owned);
1364            let name = optional(params.get("name"), "blob name", Value::as_str)
1365                .map_err(client_err)?
1366                .map(str::to_owned);
1367            let reference = need_client(client)?
1368                .upload_blob(&bytes, media_type, name)
1369                .map_err(client_err)?;
1370            Ok(json!({ "ref": reference }))
1371        }
1372        "fetchBlob" => {
1373            let blob = params
1374                .get("blob")
1375                .and_then(Value::as_str)
1376                .ok_or_else(|| client_err("fetchBlob missing blob".to_owned()))?
1377                .to_owned();
1378            // fetch_blob_bytes returns (code, message) so the server's blob.*
1379            // code reaches the caller (§5.9.5 cross-scope probe). The command
1380            // boundary owns the JSON byte encoding used by native bindings.
1381            let blob = need_client(client)?.fetch_blob_bytes(transport, &blob)?;
1382            let mut value = serde_json::Map::new();
1383            value.insert("blobId".to_owned(), Value::from(blob.blob_id));
1384            value.insert("byteLength".to_owned(), Value::from(blob.byte_length));
1385            value.insert("bytes".to_owned(), bytes_value(&blob.bytes));
1386            if let Some(media_type) = blob.media_type {
1387                value.insert("mediaType".to_owned(), Value::from(media_type));
1388            }
1389            Ok(Value::Object(serde_json::Map::from_iter([(
1390                "blob".to_owned(),
1391                Value::Object(value),
1392            )])))
1393        }
1394        "conflicts" => {
1395            let conflicts = need_client(client)?.conflicts().to_vec();
1396            Ok(json!({ "conflicts": conflicts }))
1397        }
1398        "rejections" => {
1399            let rejections = need_client(client)?.rejections().to_vec();
1400            Ok(json!({ "rejections": rejections }))
1401        }
1402        "commitOutcome" => {
1403            let client_commit_id = params
1404                .get("clientCommitId")
1405                .and_then(Value::as_str)
1406                .ok_or_else(|| {
1407                    client_err(
1408                        "sync.invalid_request: commitOutcome missing clientCommitId".to_owned(),
1409                    )
1410                })?;
1411            let outcome = need_client(client)?
1412                .commit_outcome(client_commit_id)
1413                .map_err(client_err)?;
1414            Ok(json!({ "outcome": outcome }))
1415        }
1416        "commitOutcomes" => {
1417            let query = serde_json::from_value::<CommitOutcomeQuery>(
1418                params.get("query").cloned().unwrap_or_else(|| json!({})),
1419            )
1420            .map_err(|error| {
1421                client_err(format!(
1422                    "sync.invalid_request: invalid commit outcome query: {error}"
1423                ))
1424            })?;
1425            let outcomes = need_client(client)?
1426                .commit_outcomes(query)
1427                .map_err(client_err)?;
1428            Ok(json!({ "outcomes": outcomes }))
1429        }
1430        "resolveCommitOutcome" => {
1431            let input = serde_json::from_value::<ResolveCommitOutcomeInput>(
1432                params.get("input").cloned().ok_or_else(|| {
1433                    client_err(
1434                        "sync.invalid_request: resolveCommitOutcome missing input".to_owned(),
1435                    )
1436                })?,
1437            )
1438            .map_err(|error| {
1439                client_err(format!(
1440                    "sync.invalid_request: invalid outcome resolution: {error}"
1441                ))
1442            })?;
1443            let outcome = need_client(client)?
1444                .resolve_commit_outcome(input)
1445                .map_err(client_err)?;
1446            Ok(json!({ "outcome": outcome }))
1447        }
1448        "pendingCommitIds" => {
1449            let ids = need_client(client)?.pending_commit_ids();
1450            Ok(json!({ "ids": ids }))
1451        }
1452        "pendingPayloads" => {
1453            let payloads = need_client(client)?
1454                .pending_payloads()
1455                .map_err(client_err)?;
1456            Ok(json!({
1457                "payloads": payloads.iter().map(|p| bytes_value(p)).collect::<Vec<_>>()
1458            }))
1459        }
1460        "units" => Ok(json!({ "units": need_client(client)?.units().map_err(client_err)? })),
1461        "unit" => {
1462            let id = params
1463                .get("id")
1464                .and_then(Value::as_str)
1465                .ok_or_else(|| client_err("unit missing id".to_owned()))?;
1466            Ok(json!({ "unit": need_client(client)?.unit(id).map_err(client_err)? }))
1467        }
1468        "recreateWithSchema" => {
1469            // §7.4.2 "app ships new code": swap to the new schema on the SAME
1470            // in-memory database (the Rust core has no persistent restart, so
1471            // recreation IS the boot). Fires the §7.4.1 marker check.
1472            let schema = params
1473                .get("schema")
1474                .ok_or_else(|| client_err("recreateWithSchema missing schema".to_owned()))?;
1475            need_client(client)?
1476                .recreate_with_schema(schema)
1477                .map_err(client_err)?;
1478            Ok(json!({}))
1479        }
1480        "localAuthorityState" => Ok(json!({ "state": transport.local_authority_state() })),
1481        // A native host drains buffered realtime traffic after every command;
1482        // this command does nothing else. The FFI host answers its
1483        // `realtime-wake` event with it.
1484        "drainRealtime" => Ok(json!({})),
1485        "attachLocalAuthority" | "abandonLocalAuthorityAttach" => {
1486            let running = need_client(client)?;
1487            if transport.local_authority_state().is_none() {
1488                return Err(CommandError::new(
1489                    LOCAL_AUTHORITY_UNCONFIGURED_CODE,
1490                    "the host configured no localAuthorityPath",
1491                ));
1492            }
1493            // §12.3: hold the client's rounds while the authority uploads or
1494            // rolls back, then restore the host's transport gate.
1495            let enabled = running.transport_enabled();
1496            running.set_transport_enabled(transport, false);
1497            let outcome = if method == "attachLocalAuthority" {
1498                transport.attach_local_authority()
1499            } else {
1500                transport.abandon_local_authority_attach()
1501            };
1502            running.set_transport_enabled(transport, enabled);
1503            outcome.map_err(transport_command_error)?;
1504            Ok(json!({ "effects": CommandEffects::interactive() }))
1505        }
1506        "connectRealtime" => {
1507            need_client(client)?
1508                .connect_realtime(transport)
1509                .map_err(client_err)?;
1510            Ok(json!({}))
1511        }
1512        "disconnectRealtime" => {
1513            need_client(client)?.disconnect_realtime(transport);
1514            Ok(json!({}))
1515        }
1516        "setPresence" => {
1517            let scope_key = params
1518                .get("scopeKey")
1519                .and_then(Value::as_str)
1520                .ok_or_else(|| client_err("setPresence missing scopeKey".to_owned()))?
1521                .to_owned();
1522            // §8.6.2: `doc` may be a JSON object or null (a leave).
1523            let doc = params.get("doc");
1524            let doc_ref = match doc {
1525                None | Some(Value::Null) => None,
1526                Some(v) => Some(v),
1527            };
1528            need_client(client)?
1529                .set_presence(transport, &scope_key, doc_ref)
1530                .map_err(client_err)?;
1531            Ok(json!({}))
1532        }
1533        "presence" => {
1534            let scope_key = params
1535                .get("scopeKey")
1536                .and_then(Value::as_str)
1537                .ok_or_else(|| client_err("presence missing scopeKey".to_owned()))?;
1538            let peers = need_client(client)?.presence(scope_key);
1539            Ok(json!({ "peers": peers }))
1540        }
1541
1542        // -- CodecDriver surface (Appendix A) — no client instance needed --
1543        "messageRoundtrip" => {
1544            let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1545            match decode_message(&bytes) {
1546                Ok(message) => Ok(json!({
1547                    "ok": true,
1548                    "bytes": bytes_value(&encode_message(&message)),
1549                    "renderedJson": render_message(&message).to_string(),
1550                })),
1551                Err(error) => Ok(json!({ "ok": false, "errorCode": error.code.as_str() })),
1552            }
1553        }
1554        "segmentRoundtrip" => {
1555            let bytes = value_bytes(params.get("bytes")).map_err(client_err)?;
1556            match decode_rows_segment(&bytes) {
1557                Ok(segment) => Ok(json!({
1558                    "ok": true,
1559                    "bytes": bytes_value(&encode_rows_segment(&segment)),
1560                    "renderedJson": render_rows_segment(&segment).to_string(),
1561                })),
1562                Err(error) => Ok(json!({ "ok": false, "errorCode": error.code.as_str() })),
1563            }
1564        }
1565        "realtimeKnown" => {
1566            let text = params
1567                .get("text")
1568                .and_then(Value::as_str)
1569                .ok_or_else(|| client_err("realtimeKnown missing text".to_owned()))?;
1570            let known = matches!(
1571                parse_control(text),
1572                Ok(ControlMessage::Hello { .. })
1573                    | Ok(ControlMessage::Wake { .. })
1574                    | Ok(ControlMessage::Heartbeat { .. })
1575                    | Ok(ControlMessage::Presence { .. })
1576            );
1577            Ok(json!({ "value": known }))
1578        }
1579
1580        other => Err(client_err(format!("unknown method {other:?}"))),
1581    };
1582    if client
1583        .as_ref()
1584        .is_some_and(|running| !running.transport_enabled())
1585    {
1586        if let Ok(value) = &mut result {
1587            if let Some(effects) = value.get_mut("effects").and_then(Value::as_object_mut) {
1588                effects.remove("sync");
1589            }
1590        }
1591    }
1592    result
1593}
1594
1595#[cfg(test)]
1596mod tests {
1597    use serde_json::{json, Value};
1598    use syncular_client::{
1599        Mutation, SegmentRequest, SyncClient, Transport, TransportError,
1600        SECURITY_PREFLIGHT_REQUIRED_CODE,
1601    };
1602
1603    use super::{
1604        client_err, dispatch, parse_encryption, parse_headers, parse_previous_version_context,
1605        parse_window_coverage, CreateEffects, UnitScopes,
1606    };
1607
1608    #[derive(Default)]
1609    struct NoNetwork {
1610        realtime_connects: usize,
1611        realtime_closes: usize,
1612    }
1613
1614    impl Transport for NoNetwork {
1615        fn sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1616            Err(TransportError::new("sync.transport_failed", "offline"))
1617        }
1618
1619        fn realtime_sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1620            Err(TransportError::new("sync.transport_failed", "offline"))
1621        }
1622
1623        fn download_segment(
1624            &mut self,
1625            _request: &SegmentRequest,
1626            _on_progress: &mut dyn FnMut(u64),
1627        ) -> Result<Vec<u8>, TransportError> {
1628            Err(TransportError::new("sync.transport_failed", "offline"))
1629        }
1630
1631        fn realtime_connect(&mut self) -> Result<(), TransportError> {
1632            self.realtime_connects += 1;
1633            Ok(())
1634        }
1635
1636        fn realtime_send(&mut self, _text: &str) -> Result<(), TransportError> {
1637            Ok(())
1638        }
1639
1640        fn realtime_close(&mut self) -> Result<(), TransportError> {
1641            self.realtime_closes += 1;
1642            Ok(())
1643        }
1644    }
1645
1646    fn schema() -> Value {
1647        json!({
1648            "version": 1,
1649            "tables": [{
1650                "name": "todos",
1651                "columns": [
1652                    { "name": "id", "type": "string", "nullable": false },
1653                    { "name": "list_id", "type": "string", "nullable": false }
1654                ],
1655                "primaryKey": "id",
1656                "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
1657            }]
1658        })
1659    }
1660
1661    #[test]
1662    fn native_command_realtime_connection_is_idempotent() {
1663        let mut transport = NoNetwork::default();
1664        let mut client: Option<SyncClient> = None;
1665        let mut effects = CreateEffects::default();
1666        dispatch(
1667            &mut transport,
1668            &mut client,
1669            &mut effects,
1670            "create",
1671            &json!({ "schema": schema() }),
1672        )
1673        .expect("create client");
1674
1675        for _ in 0..2 {
1676            dispatch(
1677                &mut transport,
1678                &mut client,
1679                &mut effects,
1680                "connectRealtime",
1681                &json!({}),
1682            )
1683            .expect("idempotent connect command");
1684        }
1685        assert_eq!(transport.realtime_connects, 1);
1686
1687        dispatch(
1688            &mut transport,
1689            &mut client,
1690            &mut effects,
1691            "disconnectRealtime",
1692            &json!({}),
1693        )
1694        .expect("disconnect command");
1695        dispatch(
1696            &mut transport,
1697            &mut client,
1698            &mut effects,
1699            "disconnectRealtime",
1700            &json!({}),
1701        )
1702        .expect("idempotent disconnect command");
1703        assert_eq!(transport.realtime_closes, 1);
1704        dispatch(
1705            &mut transport,
1706            &mut client,
1707            &mut effects,
1708            "connectRealtime",
1709            &json!({}),
1710        )
1711        .expect("deliberate reconnect command");
1712        assert_eq!(transport.realtime_connects, 2);
1713    }
1714
1715    #[test]
1716    fn local_authority_commands_without_one_report_the_unconfigured_code() {
1717        let mut transport = NoNetwork::default();
1718        let mut client: Option<SyncClient> = None;
1719        let mut effects = CreateEffects::default();
1720        let state = dispatch(
1721            &mut transport,
1722            &mut client,
1723            &mut effects,
1724            "localAuthorityState",
1725            &json!({}),
1726        )
1727        .expect("state without a client");
1728        assert_eq!(state, json!({ "state": null }));
1729        dispatch(
1730            &mut transport,
1731            &mut client,
1732            &mut effects,
1733            "create",
1734            &json!({ "schema": schema() }),
1735        )
1736        .expect("create client");
1737        for method in ["attachLocalAuthority", "abandonLocalAuthorityAttach"] {
1738            let error = dispatch(
1739                &mut transport,
1740                &mut client,
1741                &mut effects,
1742                method,
1743                &json!({}),
1744            )
1745            .expect_err("no local authority");
1746            assert_eq!(error.code, "client.local_authority_unconfigured");
1747        }
1748        let running = client.as_mut().expect("client");
1749        assert!(running.transport_enabled());
1750        assert!(
1751            running.drain_sync_intents().is_empty(),
1752            "the gate never toggled"
1753        );
1754    }
1755
1756    /// A host transport with a scripted §12 local authority.
1757    struct ScriptedAuthority {
1758        opened: Vec<(Value, Option<String>)>,
1759        open_error: Option<TransportError>,
1760        attach_error: Option<TransportError>,
1761        abandons: usize,
1762    }
1763
1764    impl Transport for ScriptedAuthority {
1765        fn sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1766            Err(TransportError::new("sync.transport_failed", "offline"))
1767        }
1768        fn realtime_sync(&mut self, _request: &[u8]) -> Result<Vec<u8>, TransportError> {
1769            Err(TransportError::new("sync.transport_failed", "offline"))
1770        }
1771        fn download_segment(
1772            &mut self,
1773            _request: &SegmentRequest,
1774            _on_progress: &mut dyn FnMut(u64),
1775        ) -> Result<Vec<u8>, TransportError> {
1776            Err(TransportError::new("sync.transport_failed", "offline"))
1777        }
1778        fn realtime_connect(&mut self) -> Result<(), TransportError> {
1779            Ok(())
1780        }
1781        fn realtime_send(&mut self, _text: &str) -> Result<(), TransportError> {
1782            Ok(())
1783        }
1784        fn realtime_close(&mut self) -> Result<(), TransportError> {
1785            Ok(())
1786        }
1787        fn open_local_authority(
1788            &mut self,
1789            schema: &Value,
1790            replica_path: Option<&str>,
1791        ) -> Result<(), TransportError> {
1792            self.opened
1793                .push((schema.clone(), replica_path.map(str::to_owned)));
1794            self.open_error.take().map_or(Ok(()), Err)
1795        }
1796        fn local_authority_state(&self) -> Option<&'static str> {
1797            (!self.opened.is_empty()).then_some("local")
1798        }
1799        fn attach_local_authority(&mut self) -> Result<(), TransportError> {
1800            self.attach_error.take().map_or(Ok(()), Err)
1801        }
1802        fn abandon_local_authority_attach(&mut self) -> Result<(), TransportError> {
1803            self.abandons += 1;
1804            Ok(())
1805        }
1806    }
1807
1808    #[test]
1809    fn local_authority_opens_at_create_and_attach_errors_keep_code_and_details() {
1810        let mut transport = ScriptedAuthority {
1811            opened: Vec::new(),
1812            open_error: Some(TransportError::new("sync.internal_error", "open failed")),
1813            attach_error: Some(TransportError {
1814                code: "sync.attach_rejected".to_owned(),
1815                message: "the remote server refused an attach commit".to_owned(),
1816                details: Some(json!({ "reason": "commit_rejected", "opIndex": 0 })),
1817            }),
1818            abandons: 0,
1819        };
1820        let mut client: Option<SyncClient> = None;
1821        let mut effects = CreateEffects::default();
1822        let error = dispatch(
1823            &mut transport,
1824            &mut client,
1825            &mut effects,
1826            "create",
1827            &json!({ "schema": schema() }),
1828        )
1829        .expect_err("an authority that fails to open fails create");
1830        assert_eq!(error.code, "sync.internal_error");
1831        assert!(client.is_none());
1832
1833        dispatch(
1834            &mut transport,
1835            &mut client,
1836            &mut effects,
1837            "create",
1838            &json!({ "schema": schema() }),
1839        )
1840        .expect("create client");
1841        assert_eq!(transport.opened.len(), 2);
1842        assert_eq!(transport.opened[1], (schema(), None));
1843        let state = dispatch(
1844            &mut transport,
1845            &mut client,
1846            &mut effects,
1847            "localAuthorityState",
1848            &json!({}),
1849        )
1850        .expect("state");
1851        assert_eq!(state, json!({ "state": "local" }));
1852
1853        let error = dispatch(
1854            &mut transport,
1855            &mut client,
1856            &mut effects,
1857            "attachLocalAuthority",
1858            &json!({}),
1859        )
1860        .expect_err("scripted rejection");
1861        assert_eq!(error.code, "sync.attach_rejected");
1862        assert_eq!(
1863            error.details,
1864            Some(json!({ "reason": "commit_rejected", "opIndex": 0 }))
1865        );
1866        assert!(client.as_ref().expect("client").transport_enabled());
1867
1868        let abandoned = dispatch(
1869            &mut transport,
1870            &mut client,
1871            &mut effects,
1872            "abandonLocalAuthorityAttach",
1873            &json!({}),
1874        )
1875        .expect("abandon");
1876        assert_eq!(abandoned["effects"]["sync"]["kind"], "interactive");
1877        assert_eq!(transport.abandons, 1);
1878
1879        // An offline host stays offline across attach.
1880        dispatch(
1881            &mut transport,
1882            &mut client,
1883            &mut effects,
1884            "setTransportEnabled",
1885            &json!({ "enabled": false }),
1886        )
1887        .expect("go offline");
1888        let attached = dispatch(
1889            &mut transport,
1890            &mut client,
1891            &mut effects,
1892            "attachLocalAuthority",
1893            &json!({}),
1894        )
1895        .expect("attach");
1896        assert!(attached["effects"].get("sync").is_none());
1897        assert!(!client.as_ref().expect("client").transport_enabled());
1898    }
1899
1900    #[test]
1901    fn schema_downgrade_has_structured_code_at_create_and_recreate_boundaries() {
1902        let path = temp_db_path("schema-downgrade");
1903        let mut newer = schema();
1904        newer["version"] = json!(3);
1905        let mut older = schema();
1906        older["version"] = json!(2);
1907        let mut transport = NoNetwork::default();
1908        let mut client = None;
1909        let mut effects = CreateEffects::default();
1910        dispatch(
1911            &mut transport,
1912            &mut client,
1913            &mut effects,
1914            "create",
1915            &json!({ "schema": newer, "dbPath": path }),
1916        )
1917        .expect("v3 create");
1918        let error = dispatch(
1919            &mut transport,
1920            &mut client,
1921            &mut effects,
1922            "recreateWithSchema",
1923            &json!({ "schema": older }),
1924        )
1925        .expect_err("refuse recreation");
1926        assert_eq!(error.code, "client.schema_downgrade");
1927        assert_eq!(
1928            error.message,
1929            "client.schema_downgrade: persisted local schema is newer than the requested schema"
1930        );
1931        dispatch(
1932            &mut transport,
1933            &mut client,
1934            &mut effects,
1935            "shutdown",
1936            &json!({}),
1937        )
1938        .expect("shutdown");
1939        let error = dispatch(
1940            &mut transport,
1941            &mut client,
1942            &mut effects,
1943            "create",
1944            &json!({ "schema": older, "dbPath": path }),
1945        )
1946        .expect_err("refuse open");
1947        assert_eq!(error.code, "client.schema_downgrade");
1948        assert!(client.is_none());
1949        dispatch(
1950            &mut transport,
1951            &mut client,
1952            &mut effects,
1953            "create",
1954            &json!({ "schema": newer, "dbPath": path }),
1955        )
1956        .expect("compatible reopen");
1957        dispatch(
1958            &mut transport,
1959            &mut client,
1960            &mut effects,
1961            "shutdown",
1962            &json!({}),
1963        )
1964        .expect("shutdown");
1965        let _ = std::fs::remove_file(path);
1966    }
1967
1968    #[test]
1969    fn native_command_realtime_policy_rides_create_and_refuses_http() {
1970        let mut transport = NoNetwork::default();
1971        let mut client: Option<SyncClient> = None;
1972        let mut effects = CreateEffects::default();
1973        dispatch(
1974            &mut transport,
1975            &mut client,
1976            &mut effects,
1977            "create",
1978            &json!({ "schema": schema(), "realtimePolicy": "required" }),
1979        )
1980        .expect("create client with a required realtime policy");
1981        let result = dispatch(
1982            &mut transport,
1983            &mut client,
1984            &mut effects,
1985            "sync",
1986            &json!({}),
1987        )
1988        .expect("sync command");
1989        assert_eq!(result["ok"], json!(false));
1990        assert_eq!(result["errorCode"], json!("sync.realtime_unavailable"));
1991        assert_eq!(result["realtimeState"], json!("disconnected"));
1992        assert_eq!(result["retryDelayMs"], json!(250));
1993        let snapshot = dispatch(
1994            &mut transport,
1995            &mut client,
1996            &mut effects,
1997            "diagnosticsSnapshot",
1998            &json!({}),
1999        )
2000        .expect("diagnostics command");
2001        assert_eq!(snapshot["host"]["realtime"], json!("disconnected"));
2002        assert_eq!(snapshot["host"]["realtimePolicy"], json!("required"));
2003        assert_eq!(snapshot["host"]["realtimeRetryDelayMs"], json!(250));
2004
2005        let mut second: Option<SyncClient> = None;
2006        let error = dispatch(
2007            &mut transport,
2008            &mut second,
2009            &mut effects,
2010            "create",
2011            &json!({ "schema": schema(), "realtimePolicy": "always" }),
2012        )
2013        .expect_err("an unknown policy is refused");
2014        assert_eq!(error.code, "sync.invalid_request");
2015    }
2016
2017    #[test]
2018    fn parses_portable_encryption_keyring_and_key_id_columns() {
2019        let key_hex = "2a".repeat(32);
2020        let config = parse_encryption(&json!({
2021            "keys": { "practice-key-v1": { "$bytes": key_hex } },
2022            "keyIdColumns": { "patients": "encryption_key_id" }
2023        }))
2024        .expect("portable keyring parses");
2025        assert_eq!(config.keys["practice-key-v1"], vec![0x2a; 32]);
2026        assert_eq!(config.key_id_columns["patients"], "encryption_key_id");
2027    }
2028
2029    #[test]
2030    fn rejects_non_string_key_id_columns() {
2031        let error = parse_encryption(&json!({
2032            "keys": {},
2033            "keyIdColumns": { "patients": 7 }
2034        }))
2035        .expect_err("invalid selector must fail");
2036        assert!(error.contains("must be a string"), "{error}");
2037    }
2038
2039    #[test]
2040    fn subscribe_many_registers_every_unit() {
2041        let mut transport = NoNetwork::default();
2042        let mut client: Option<SyncClient> = None;
2043        let mut effects = CreateEffects::default();
2044        let mut run = |command: &str, params: Value| {
2045            dispatch(&mut transport, &mut client, &mut effects, command, &params)
2046        };
2047        run("create", json!({ "schema": schema() })).expect("create client");
2048        let ids = run(
2049            "subscribeMany",
2050            json!({ "units": [{ "list_id": "list-1" }, { "list_id": "list-2" }] }),
2051        )
2052        .expect("register units")["ids"]
2053            .clone();
2054        let single = run("subscribe", json!({ "scopes": { "list_id": "list-1" } }))
2055            .expect("re-register a unit");
2056        assert_eq!(single["id"], ids[0], "a unit id derives from its scope map");
2057        let units = run("units", json!({})).expect("units");
2058        assert_eq!(units["units"].as_array().map(Vec::len), Some(2));
2059        for (index, list) in ["list-1", "list-2"].into_iter().enumerate() {
2060            let unit = run("unit", json!({ "id": ids[index] })).expect("unit");
2061            assert_eq!(unit["unit"]["scopes"], json!({ "list_id": list }));
2062            assert_eq!(unit["unit"]["cursor"], -1);
2063        }
2064        assert_eq!(
2065            run("unit", json!({ "id": "absent" })).expect("unit")["unit"],
2066            Value::Null
2067        );
2068        for scopes in [json!({ "list_id": "*" }), json!({ "other": "x" })] {
2069            let error = run("subscribe", json!({ "scopes": scopes }))
2070                .expect_err("a unit names a non-wildcard value per covered variable");
2071            assert_eq!(error.code, "sync.invalid_subscription", "{scopes}");
2072        }
2073    }
2074
2075    #[test]
2076    fn window_coverage_parser_reads_the_generated_descriptor_and_rejects_malformed_units() {
2077        let parsed = parse_window_coverage(Some(&json!([{
2078            "base": { "variable": "project_id", "fixedScopes": { "tenant_id": "one" } },
2079            "units": ["a", "b"]
2080        }])))
2081        .expect("parse coverage");
2082        assert_eq!(parsed[0].base.variable, "project_id");
2083        assert_eq!(
2084            parsed[0].base.fixed_scopes,
2085            UnitScopes::from([("tenant_id".to_owned(), "one".to_owned())])
2086        );
2087        assert_eq!(parsed[0].units, ["a", "b"]);
2088        for coverage in [
2089            json!({}),
2090            json!([{ "base": { "variable": "project_id" }, "units": ["a", 1] }]),
2091            json!([{ "base": { "fixedScopes": {} }, "units": [] }]),
2092        ] {
2093            let error = parse_window_coverage(Some(&coverage)).expect_err("malformed coverage");
2094            assert!(error.starts_with("sync.invalid_request: "), "{error}");
2095        }
2096    }
2097
2098    #[test]
2099    fn subscribe_and_unsubscribe_queue_an_interactive_sync_intent() {
2100        let mut transport = NoNetwork::default();
2101        let mut client: Option<SyncClient> = None;
2102        let mut effects = CreateEffects::default();
2103        let mut run = |command: &str, params: Value| {
2104            dispatch(&mut transport, &mut client, &mut effects, command, &params)
2105                .expect("command succeeds")
2106        };
2107        run("create", json!({ "schema": schema() }));
2108        run("drainSyncIntents", json!({}));
2109        let id = run("subscribe", json!({ "scopes": { "list_id": "list-1" } }))["id"].clone();
2110        let intents = run("drainSyncIntents", json!({}));
2111        assert_eq!(intents["intents"], json!([{ "kind": "interactive" }]));
2112        run("unsubscribe", json!({ "id": id }));
2113        let intents = run("drainSyncIntents", json!({}));
2114        assert_eq!(intents["intents"], json!([{ "kind": "interactive" }]));
2115    }
2116
2117    #[test]
2118    fn security_preflight_is_fail_closed_until_exact_activation() {
2119        let mut transport = NoNetwork::default();
2120        let mut client: Option<SyncClient> = None;
2121        let mut effects = CreateEffects::default();
2122        dispatch(
2123            &mut transport,
2124            &mut client,
2125            &mut effects,
2126            "create",
2127            &json!({ "schema": schema(), "securityPreflight": true }),
2128        )
2129        .expect("preflight create");
2130
2131        let lifecycle = dispatch(
2132            &mut transport,
2133            &mut client,
2134            &mut effects,
2135            "securityLifecycle",
2136            &json!({}),
2137        )
2138        .expect("lifecycle");
2139        assert_eq!(lifecycle, json!({ "state": "preflight" }));
2140
2141        let query_error = dispatch(
2142            &mut transport,
2143            &mut client,
2144            &mut effects,
2145            "query",
2146            &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2147        )
2148        .expect_err("protected query must fail");
2149        assert_eq!(query_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2150        let diagnostics_error = dispatch(
2151            &mut transport,
2152            &mut client,
2153            &mut effects,
2154            "diagnosticsSnapshot",
2155            &json!({}),
2156        )
2157        .expect_err("diagnostics unit evidence remains protected");
2158        assert_eq!(diagnostics_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2159
2160        dispatch(
2161            &mut transport,
2162            &mut client,
2163            &mut effects,
2164            "purgeLocalData",
2165            &json!({
2166                "input": {
2167                    "purgeId": "directive-1",
2168                    "targets": [{
2169                        "table": "todos",
2170                        "selectors": { "list_id": ["list-1"] }
2171                    }]
2172                }
2173            }),
2174        )
2175        .expect("authorized local purge remains available");
2176
2177        let repair_error = dispatch(
2178            &mut transport,
2179            &mut client,
2180            &mut effects,
2181            "rebootstrapLocalData",
2182            &json!({ "input": { "rebootstrapId": "blocked-repair" } }),
2183        )
2184        .expect_err("projection repair must remain protected during preflight");
2185        assert_eq!(repair_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2186
2187        dispatch(
2188            &mut transport,
2189            &mut client,
2190            &mut effects,
2191            "activateSecurity",
2192            &json!({}),
2193        )
2194        .expect("activation");
2195        let rows = dispatch(
2196            &mut transport,
2197            &mut client,
2198            &mut effects,
2199            "query",
2200            &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2201        )
2202        .expect("active query");
2203        assert_eq!(rows, json!({ "rows": [] }));
2204
2205        dispatch(
2206            &mut transport,
2207            &mut client,
2208            &mut effects,
2209            "beginSecurityPreflight",
2210            &json!({}),
2211        )
2212        .expect("re-enter preflight");
2213        let blocked = dispatch(
2214            &mut transport,
2215            &mut client,
2216            &mut effects,
2217            "mutate",
2218            &json!({ "mutations": [] }),
2219        )
2220        .expect_err("mutation must be gated");
2221        assert_eq!(blocked.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2222    }
2223
2224    #[test]
2225    fn mutate_and_patch_forward_typed_storage_failures() {
2226        let path = temp_db_path("busy-authoring");
2227        let schema = json!({
2228            "version": 1,
2229            "tables": [{
2230                "name": "todos",
2231                "columns": [
2232                    { "name": "id", "type": "string", "nullable": false },
2233                    { "name": "list_id", "type": "string", "nullable": false },
2234                    { "name": "title", "type": "string", "nullable": false }
2235                ],
2236                "primaryKey": "id",
2237                "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
2238            }]
2239        });
2240        let mut transport = NoNetwork::default();
2241        let mut client: Option<SyncClient> = None;
2242        let mut effects = CreateEffects::default();
2243        dispatch(
2244            &mut transport,
2245            &mut client,
2246            &mut effects,
2247            "create",
2248            &json!({ "schema": schema, "dbPath": path }),
2249        )
2250        .expect("create file-backed client");
2251        let upsert = |id: &str| {
2252            json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2253                "id": id, "list_id": "l1", "title": "first" } }] })
2254        };
2255        dispatch(
2256            &mut transport,
2257            &mut client,
2258            &mut effects,
2259            "mutate",
2260            &upsert("t1"),
2261        )
2262        .expect("seed row");
2263
2264        let locker = rusqlite::Connection::open(&path).expect("second connection");
2265        locker.execute_batch("BEGIN IMMEDIATE").unwrap();
2266        let busy = dispatch(
2267            &mut transport,
2268            &mut client,
2269            &mut effects,
2270            "mutate",
2271            &upsert("t2"),
2272        )
2273        .expect_err("busy mutate");
2274        assert_eq!(busy.code, "client.storage_busy");
2275        assert!(busy.retryable);
2276        assert_eq!(busy.details.as_ref().unwrap()["sqliteCode"], 5);
2277
2278        let busy_patch = dispatch(
2279            &mut transport,
2280            &mut client,
2281            &mut effects,
2282            "patch",
2283            &json!({ "table": "todos", "rowId": "t1", "partial": { "title": "second" } }),
2284        )
2285        .expect_err("busy patch");
2286        assert_eq!(busy_patch.code, "client.storage_busy");
2287        assert!(busy_patch.retryable);
2288        assert_eq!(busy_patch.details.as_ref().unwrap()["sqliteCode"], 5);
2289
2290        locker.execute_batch("ROLLBACK").unwrap();
2291        let retried = dispatch(
2292            &mut transport,
2293            &mut client,
2294            &mut effects,
2295            "mutate",
2296            &upsert("t2"),
2297        )
2298        .expect("retry after busy");
2299        assert!(retried.get("clientCommitId").is_some());
2300        let _ = std::fs::remove_file(&path);
2301    }
2302
2303    #[test]
2304    fn read_command_error_preserves_code_details_and_retryability() {
2305        let corrupt = super::read_command_error(syncular_client::QueryReadFailure {
2306            code: Some("sync.local_corrupt"),
2307            sqlite_code: None,
2308            sqlite_message: None,
2309            rollback_failure: None,
2310            message: "persisted local revision is invalid".to_owned(),
2311        });
2312        assert_eq!(corrupt.code, "sync.local_corrupt");
2313        assert!(!corrupt.retryable);
2314        assert!(corrupt.details.is_none());
2315
2316        let busy = super::read_command_error(syncular_client::QueryReadFailure {
2317            code: Some("client.storage_busy"),
2318            sqlite_code: Some(5),
2319            sqlite_message: Some("database is locked".to_owned()),
2320            rollback_failure: None,
2321            message: "local SQLite storage is busy".to_owned(),
2322        });
2323        assert_eq!(busy.code, "client.storage_busy");
2324        assert!(busy.retryable);
2325        assert_eq!(
2326            busy.details.expect("busy details")["sqliteCode"],
2327            serde_json::json!(5)
2328        );
2329    }
2330
2331    #[test]
2332    fn mutate_and_patch_report_caller_value_failures_as_invalid_request() {
2333        let path = temp_db_path("caller-values");
2334        let schema = json!({
2335            "version": 1,
2336            "tables": [{
2337                "name": "todos",
2338                "columns": [
2339                    { "name": "id", "type": "string", "nullable": false },
2340                    { "name": "list_id", "type": "string", "nullable": false },
2341                    { "name": "title", "type": "string", "nullable": false },
2342                    { "name": "priority", "type": "integer", "nullable": false }
2343                ],
2344                "primaryKey": "id",
2345                "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
2346            }]
2347        });
2348        let mut transport = NoNetwork::default();
2349        let mut client: Option<SyncClient> = None;
2350        let mut effects = CreateEffects::default();
2351        dispatch(
2352            &mut transport,
2353            &mut client,
2354            &mut effects,
2355            "create",
2356            &json!({ "schema": schema, "dbPath": path }),
2357        )
2358        .expect("create file-backed client");
2359        let seed = dispatch(
2360            &mut transport,
2361            &mut client,
2362            &mut effects,
2363            "mutate",
2364            &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2365                "id": "t1", "list_id": "l1", "title": "first", "priority": 1 } }] }),
2366        )
2367        .expect("seed row");
2368        let seed_id = seed["clientCommitId"].clone();
2369
2370        // §6.1/§7.1: a caller value the authoring seam rejects is an invalid
2371        // request, not the internal-failure default.
2372        let unknown = dispatch(
2373            &mut transport,
2374            &mut client,
2375            &mut effects,
2376            "mutate",
2377            &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2378                "id": "t2", "list_id": "l1", "title": "second", "priority": 1,
2379                "missing_column": 1 } }] }),
2380        )
2381        .expect_err("unknown column");
2382        assert_eq!(unknown.code, "sync.invalid_request");
2383        assert_eq!(unknown.message, "the authoring request is invalid");
2384        assert!(!unknown.retryable);
2385        assert!(unknown.details.as_ref().unwrap()["legacyCause"]
2386            .as_str()
2387            .unwrap()
2388            .contains("unknown column"));
2389
2390        let bad_patch = dispatch(
2391            &mut transport,
2392            &mut client,
2393            &mut effects,
2394            "patch",
2395            &json!({ "table": "todos", "rowId": "t1", "partial": { "priority": "high" } }),
2396        )
2397        .expect_err("bad patch value");
2398        assert_eq!(bad_patch.code, "sync.invalid_request");
2399        assert_eq!(bad_patch.message, "the authoring request is invalid");
2400        assert!(bad_patch.details.as_ref().unwrap()["legacyCause"]
2401            .as_str()
2402            .unwrap()
2403            .contains("priority"));
2404
2405        // Neither rejection enqueued a commit or touched the projection.
2406        let pending = dispatch(
2407            &mut transport,
2408            &mut client,
2409            &mut effects,
2410            "pendingCommitIds",
2411            &json!({}),
2412        )
2413        .expect("pending commit ids");
2414        assert_eq!(pending["ids"], json!([seed_id]));
2415        let rows = dispatch(
2416            &mut transport,
2417            &mut client,
2418            &mut effects,
2419            "query",
2420            &json!({ "sql": "SELECT id, priority FROM todos ORDER BY id" }),
2421        )
2422        .expect("visible rows");
2423        assert_eq!(rows["rows"], json!([{ "id": "t1", "priority": 1 }]));
2424
2425        // The next valid call authorizes normally.
2426        let accepted = dispatch(
2427            &mut transport,
2428            &mut client,
2429            &mut effects,
2430            "mutate",
2431            &json!({ "mutations": [{ "op": "upsert", "table": "todos", "values": {
2432                "id": "t2", "list_id": "l1", "title": "second", "priority": 2 } }] }),
2433        )
2434        .expect("retry after rejection");
2435        assert!(accepted.get("clientCommitId").is_some());
2436        let _ = std::fs::remove_file(&path);
2437    }
2438
2439    #[test]
2440    fn client_err_preserves_retryable_for_storage_busy() {
2441        let busy = client_err("client.storage_busy: local SQLite storage is busy".to_owned());
2442        assert_eq!(busy.code, "client.storage_busy");
2443        assert!(busy.retryable);
2444        // The legacy boundary keeps the full rendered message.
2445        assert_eq!(
2446            busy.message,
2447            "client.storage_busy: local SQLite storage is busy"
2448        );
2449        let full = client_err("client.storage_full: local SQLite storage is full".to_owned());
2450        assert_eq!(full.code, "client.storage_full");
2451        assert!(!full.retryable);
2452    }
2453
2454    #[test]
2455    fn client_err_keeps_a_colon_less_code_identity() {
2456        let error = client_err("sync.unknown_table".to_owned());
2457        assert_eq!(error.code, "sync.unknown_table");
2458        let error = client_err("no client instance created".to_owned());
2459        assert_eq!(error.code, "client.failed");
2460    }
2461
2462    #[cfg(feature = "crdt-yjs")]
2463    #[test]
2464    fn crdt_offsets_outside_u32_are_invalid_requests() {
2465        let mut transport = NoNetwork::default();
2466        let mut client: Option<SyncClient> = None;
2467        let mut effects = CreateEffects::default();
2468        dispatch(
2469            &mut transport,
2470            &mut client,
2471            &mut effects,
2472            "create",
2473            &json!({ "schema": schema() }),
2474        )
2475        .expect("create");
2476        let target = json!({ "table": "todos", "rowId": "t1", "column": "body" });
2477        for (method, extra) in [
2478            (
2479                "crdtInsertText",
2480                json!({ "index": 4_294_967_296u64, "value": "x" }),
2481            ),
2482            ("crdtInsertText", json!({ "index": "0", "value": "x" })),
2483            (
2484                "crdtDeleteText",
2485                json!({ "index": 0, "len": 4_294_967_296u64 }),
2486            ),
2487        ] {
2488            let mut params = target.clone();
2489            params
2490                .as_object_mut()
2491                .unwrap()
2492                .extend(extra.as_object().unwrap().clone());
2493            let error = dispatch(&mut transport, &mut client, &mut effects, method, &params)
2494                .expect_err("out-of-range offset");
2495            assert_eq!(error.code, "sync.invalid_request", "{method} {params}");
2496        }
2497    }
2498
2499    #[test]
2500    fn wrong_typed_optional_fields_are_invalid_requests() {
2501        let created = || {
2502            let mut transport = NoNetwork::default();
2503            let mut client: Option<SyncClient> = None;
2504            let mut effects = CreateEffects::default();
2505            dispatch(
2506                &mut transport,
2507                &mut client,
2508                &mut effects,
2509                "create",
2510                &json!({ "schema": schema() }),
2511            )
2512            .expect("create");
2513            (transport, client, effects)
2514        };
2515        for params in [
2516            json!({ "schema": schema(), "limits": "x" }),
2517            json!({ "schema": schema(), "limits": { "accept": 256 } }),
2518            json!({ "schema": schema(), "limits": { "accept": "15" } }),
2519            json!({ "schema": schema(), "limits": { "limitCommits": 4_294_967_296i64 } }),
2520            json!({ "schema": schema(), "limits": { "outcomeRetentionMaxEntries": -1 } }),
2521            json!({ "schema": schema(), "clientId": 7 }),
2522            json!({ "schema": schema(), "nowMs": "1" }),
2523            json!({ "schema": schema(), "signedUrls": "true" }),
2524            json!({ "schema": schema(), "securityPreflight": 1 }),
2525            json!({ "schema": schema(), "encryption": { "keys": "k" } }),
2526        ] {
2527            let mut transport = NoNetwork::default();
2528            let mut client: Option<SyncClient> = None;
2529            let mut effects = CreateEffects::default();
2530            let error = dispatch(&mut transport, &mut client, &mut effects, "create", &params)
2531                .expect_err("wrong-typed create field");
2532            assert_eq!(error.code, "sync.invalid_request", "{params}");
2533        }
2534        let base = json!({ "variable": "list_id" });
2535        for (method, params) in [
2536            ("setWindow", json!({ "base": base, "units": [1] })),
2537            ("setWindow", json!({ "base": base, "units": "l1" })),
2538            (
2539                "setWindow",
2540                json!({ "base": { "variable": "list_id", "fixedScopes": ["x"] }, "units": [] }),
2541            ),
2542            ("windowState", json!({ "base": {} })),
2543            (
2544                "mutate",
2545                json!({ "mutations": [{ "op": "delete", "table": "todos", "rowId": "t1", "baseVersion": "7" }] }),
2546            ),
2547            (
2548                "patch",
2549                json!({ "table": "todos", "rowId": "t1", "partial": { "title": "x" }, "baseVersion": "7" }),
2550            ),
2551            ("subscribe", json!({ "scopes": { "list_id": ["l1"] } })),
2552            (
2553                "subscribeMany",
2554                json!({ "units": [{ "list_id": "l1" }, 7] }),
2555            ),
2556            (
2557                "uploadBlob",
2558                json!({ "bytes": { "$bytes": "00" }, "mediaType": 1 }),
2559            ),
2560        ] {
2561            let (mut transport, mut client, mut effects) = created();
2562            let error = dispatch(&mut transport, &mut client, &mut effects, method, &params)
2563                .expect_err("wrong-typed field");
2564            assert_eq!(error.code, "sync.invalid_request", "{method} {params}");
2565        }
2566        // An absent or null optional field keeps its default.
2567        let (mut transport, mut client, mut effects) = created();
2568        dispatch(
2569            &mut transport,
2570            &mut client,
2571            &mut effects,
2572            "mutate",
2573            &json!({ "mutations": [{ "op": "delete", "table": "todos", "rowId": "t1", "baseVersion": null }] }),
2574        )
2575        .expect("null baseVersion is absent");
2576    }
2577
2578    #[test]
2579    fn sync_until_idle_rejects_an_invalid_max_rounds_budget() {
2580        for value in [json!(0), json!(-1), json!(1.5), json!(4_294_967_296u64)] {
2581            let mut transport = NoNetwork::default();
2582            let mut client: Option<SyncClient> = None;
2583            let mut effects = CreateEffects::default();
2584            dispatch(
2585                &mut transport,
2586                &mut client,
2587                &mut effects,
2588                "create",
2589                &json!({ "schema": schema() }),
2590            )
2591            .expect("create");
2592            let error = dispatch(
2593                &mut transport,
2594                &mut client,
2595                &mut effects,
2596                "syncUntilIdle",
2597                &json!({ "maxRounds": value }),
2598            )
2599            .expect_err("invalid budget");
2600            assert_eq!(error.code, "sync.invalid_request", "{value}");
2601        }
2602    }
2603
2604    #[test]
2605    fn sync_until_idle_rejects_an_invalid_timeout() {
2606        for value in [json!(0), json!(-1), json!(1.5)] {
2607            let mut transport = NoNetwork::default();
2608            let mut client: Option<SyncClient> = None;
2609            let mut effects = CreateEffects::default();
2610            dispatch(
2611                &mut transport,
2612                &mut client,
2613                &mut effects,
2614                "create",
2615                &json!({ "schema": schema() }),
2616            )
2617            .expect("create");
2618            let error = dispatch(
2619                &mut transport,
2620                &mut client,
2621                &mut effects,
2622                "syncUntilIdle",
2623                &json!({ "timeoutMs": value }),
2624            )
2625            .expect_err("invalid timeout");
2626            assert_eq!(error.code, "sync.invalid_request", "{value}");
2627        }
2628    }
2629
2630    #[test]
2631    fn create_rejects_invalid_push_limits() {
2632        for value in [json!(0), json!(-1), json!(1.5), json!(4_294_967_296u64)] {
2633            let mut transport = NoNetwork::default();
2634            let mut client: Option<SyncClient> = None;
2635            let mut effects = CreateEffects::default();
2636            let error = dispatch(
2637                &mut transport,
2638                &mut client,
2639                &mut effects,
2640                "create",
2641                &json!({
2642                    "schema": schema(),
2643                    "limits": { "maxPushRequestBytes": value }
2644                }),
2645            )
2646            .expect_err("invalid push limit");
2647            assert_eq!(error.code, "sync.invalid_request", "{value}");
2648            assert_eq!(
2649                error.details.as_ref().unwrap()["limit"],
2650                json!("maxPushRequestBytes")
2651            );
2652        }
2653    }
2654
2655    #[test]
2656    fn preflight_allows_only_the_authorized_previous_version_discard() {
2657        let mut transport = NoNetwork::default();
2658        let mut client: Option<SyncClient> = None;
2659        let mut effects = CreateEffects::default();
2660        dispatch(
2661            &mut transport,
2662            &mut client,
2663            &mut effects,
2664            "create",
2665            &json!({ "schema": schema(), "securityPreflight": true }),
2666        )
2667        .expect("preflight create");
2668
2669        // Reads and the audit observe protected local data: still gated.
2670        for method in ["previousVersionSnapshot", "previousVersionAudit"] {
2671            let error = dispatch(
2672                &mut transport,
2673                &mut client,
2674                &mut effects,
2675                method,
2676                &json!({}),
2677            )
2678            .expect_err("previous-version reads stay gated during preflight");
2679            assert_eq!(error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2680        }
2681        // RFC 0006 runs the discard consumer inside the quiesced window, so the
2682        // command router must permit it (feature off here: a clean no-op).
2683        let discarded = dispatch(
2684            &mut transport,
2685            &mut client,
2686            &mut effects,
2687            "previousVersionDiscard",
2688            &json!({}),
2689        )
2690        .expect("authorized cleanup is allowed during preflight");
2691        assert_eq!(discarded, json!({ "present": false, "discarded": false }));
2692        assert!(client.as_ref().is_some_and(SyncClient::security_preflight));
2693    }
2694
2695    #[test]
2696    fn preflight_refuses_a_replacement_create_without_the_flag() {
2697        let mut transport = NoNetwork::default();
2698        let mut client: Option<SyncClient> = None;
2699        let mut effects = CreateEffects::default();
2700        dispatch(
2701            &mut transport,
2702            &mut client,
2703            &mut effects,
2704            "create",
2705            &json!({ "schema": schema(), "securityPreflight": true }),
2706        )
2707        .expect("preflight create");
2708
2709        // The escape the gate exists to prevent: a plain re-create must fail.
2710        let escape = dispatch(
2711            &mut transport,
2712            &mut client,
2713            &mut effects,
2714            "create",
2715            &json!({ "schema": schema() }),
2716        )
2717        .expect_err("plain create must be refused during preflight");
2718        assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2719        // The refused create left the preflighted client installed and gated.
2720        let query_error = dispatch(
2721            &mut transport,
2722            &mut client,
2723            &mut effects,
2724            "query",
2725            &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2726        )
2727        .expect_err("protected query stays gated");
2728        assert_eq!(query_error.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2729
2730        // A preflighted replacement is permitted and stays gated.
2731        dispatch(
2732            &mut transport,
2733            &mut client,
2734            &mut effects,
2735            "create",
2736            &json!({ "schema": schema(), "securityPreflight": true }),
2737        )
2738        .expect("preflighted replacement create");
2739        let still_gated = dispatch(
2740            &mut transport,
2741            &mut client,
2742            &mut effects,
2743            "query",
2744            &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2745        )
2746        .expect_err("replacement stays gated");
2747        assert_eq!(still_gated.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2748
2749        // A legitimate activation releases the gate; creates behave as today.
2750        dispatch(
2751            &mut transport,
2752            &mut client,
2753            &mut effects,
2754            "activateSecurity",
2755            &json!({}),
2756        )
2757        .expect("activation");
2758        dispatch(
2759            &mut transport,
2760            &mut client,
2761            &mut effects,
2762            "create",
2763            &json!({ "schema": schema() }),
2764        )
2765        .expect("plain create after activation");
2766        let rows = dispatch(
2767            &mut transport,
2768            &mut client,
2769            &mut effects,
2770            "query",
2771            &json!({ "sql": "SELECT id FROM todos", "params": [] }),
2772        )
2773        .expect("active query");
2774        assert_eq!(rows, json!({ "rows": [] }));
2775    }
2776
2777    /// A file-backed replica: the persisted quarantine marker only exists here,
2778    /// which is why the in-memory tests above could not catch this.
2779    fn temp_db_path(tag: &str) -> String {
2780        std::env::temp_dir()
2781            .join(format!(
2782                "syncular-command-{tag}-{}-{:?}.db",
2783                std::process::id(),
2784                std::time::SystemTime::now()
2785                    .duration_since(std::time::UNIX_EPOCH)
2786                    .expect("clock")
2787                    .as_nanos()
2788            ))
2789            .to_string_lossy()
2790            .into_owned()
2791    }
2792
2793    #[test]
2794    fn an_activated_replica_reopens_plainly_after_shutdown() {
2795        // Shutting an ACTIVATED client down is not a quarantine event. The
2796        // teardown barrier used to call `begin_security_preflight`, which now
2797        // persists the gate, so every cleanly closed replica was marked pending
2798        // and its next plain `create` was refused forever — the reopen path
2799        // restores the flag from the marker and the create guard rejects it.
2800        let path = temp_db_path("activated-reopen");
2801        let mut transport = NoNetwork::default();
2802        let mut client: Option<SyncClient> = None;
2803        let mut effects = CreateEffects::default();
2804
2805        dispatch(
2806            &mut transport,
2807            &mut client,
2808            &mut effects,
2809            "create",
2810            &json!({ "schema": schema(), "securityPreflight": true, "dbPath": path }),
2811        )
2812        .expect("preflight create");
2813        dispatch(
2814            &mut transport,
2815            &mut client,
2816            &mut effects,
2817            "activateSecurity",
2818            &json!({}),
2819        )
2820        .expect("activation clears the gate");
2821        dispatch(
2822            &mut transport,
2823            &mut client,
2824            &mut effects,
2825            "shutdown",
2826            &json!({}),
2827        )
2828        .expect("shutdown after activation");
2829
2830        // The replica is active on disk, so a plain re-create must be admitted.
2831        dispatch(
2832            &mut transport,
2833            &mut client,
2834            &mut effects,
2835            "create",
2836            &json!({ "schema": schema(), "dbPath": path }),
2837        )
2838        .expect("an activated replica must reopen plainly after shutdown");
2839        let state = dispatch(
2840            &mut transport,
2841            &mut client,
2842            &mut effects,
2843            "securityLifecycle",
2844            &json!({}),
2845        )
2846        .expect("lifecycle");
2847        assert_eq!(state, json!({ "state": "active" }));
2848
2849        let _ = std::fs::remove_file(&path);
2850    }
2851
2852    #[test]
2853    fn an_unactivated_replica_stays_quarantined_across_shutdown_on_disk() {
2854        // The other half, and the reason the marker exists: a replica that
2855        // entered preflight and never activated must still refuse a plain
2856        // re-create after shutdown, even on a host that rebuilt its handle and
2857        // carries no in-memory flag.
2858        let path = temp_db_path("quarantined-reopen");
2859        let mut transport = NoNetwork::default();
2860        let mut client: Option<SyncClient> = None;
2861        let mut effects = CreateEffects::default();
2862
2863        dispatch(
2864            &mut transport,
2865            &mut client,
2866            &mut effects,
2867            "create",
2868            &json!({ "schema": schema(), "securityPreflight": true, "dbPath": path }),
2869        )
2870        .expect("preflight create");
2871        dispatch(
2872            &mut transport,
2873            &mut client,
2874            &mut effects,
2875            "shutdown",
2876            &json!({}),
2877        )
2878        .expect("shutdown during preflight");
2879
2880        // A fresh host handle: no in-memory pending flag survives here, so only
2881        // the persisted marker can hold the gate.
2882        let mut rebuilt = CreateEffects::default();
2883        let escape = dispatch(
2884            &mut transport,
2885            &mut client,
2886            &mut rebuilt,
2887            "create",
2888            &json!({ "schema": schema(), "dbPath": path }),
2889        )
2890        .expect_err("a quarantined replica must refuse a plain re-create");
2891        assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2892
2893        let _ = std::fs::remove_file(&path);
2894    }
2895
2896    #[test]
2897    fn preflight_gate_survives_shutdown_before_replacement_creates() {
2898        let mut transport = NoNetwork::default();
2899        let mut client: Option<SyncClient> = None;
2900        let mut effects = CreateEffects::default();
2901        dispatch(
2902            &mut transport,
2903            &mut client,
2904            &mut effects,
2905            "create",
2906            &json!({ "schema": schema(), "securityPreflight": true }),
2907        )
2908        .expect("preflight create");
2909        dispatch(
2910            &mut transport,
2911            &mut client,
2912            &mut effects,
2913            "shutdown",
2914            &json!({}),
2915        )
2916        .expect("shutdown during preflight");
2917        assert!(client.is_none());
2918
2919        // The pending preflight rides `effects` across the empty client slot.
2920        let escape = dispatch(
2921            &mut transport,
2922            &mut client,
2923            &mut effects,
2924            "create",
2925            &json!({ "schema": schema() }),
2926        )
2927        .expect_err("shutdown + plain create must stay refused");
2928        assert_eq!(escape.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
2929
2930        dispatch(
2931            &mut transport,
2932            &mut client,
2933            &mut effects,
2934            "create",
2935            &json!({ "schema": schema(), "securityPreflight": true }),
2936        )
2937        .expect("preflighted re-create");
2938        dispatch(
2939            &mut transport,
2940            &mut client,
2941            &mut effects,
2942            "activateSecurity",
2943            &json!({}),
2944        )
2945        .expect("activation");
2946
2947        // An ACTIVATED client shut down cleanly may be recreated plainly.
2948        dispatch(
2949            &mut transport,
2950            &mut client,
2951            &mut effects,
2952            "shutdown",
2953            &json!({}),
2954        )
2955        .expect("shutdown after activation");
2956        dispatch(
2957            &mut transport,
2958            &mut client,
2959            &mut effects,
2960            "create",
2961            &json!({ "schema": schema() }),
2962        )
2963        .expect("plain create after an activated shutdown");
2964    }
2965
2966    #[test]
2967    fn activate_security_validates_optional_headers_atomically() {
2968        let mut transport = NoNetwork::default();
2969        let mut client: Option<SyncClient> = None;
2970        let mut effects = CreateEffects::default();
2971        dispatch(
2972            &mut transport,
2973            &mut client,
2974            &mut effects,
2975            "create",
2976            &json!({ "schema": schema(), "securityPreflight": true }),
2977        )
2978        .expect("preflight create");
2979
2980        // Invalid header shapes fail loudly and keep the gate closed.
2981        let invalid = dispatch(
2982            &mut transport,
2983            &mut client,
2984            &mut effects,
2985            "activateSecurity",
2986            &json!({ "headers": { "authorization": 7 } }),
2987        )
2988        .expect_err("non-string header must fail");
2989        assert_eq!(invalid.code, "sync.invalid_request");
2990        let lifecycle = dispatch(
2991            &mut transport,
2992            &mut client,
2993            &mut effects,
2994            "securityLifecycle",
2995            &json!({}),
2996        )
2997        .expect("lifecycle");
2998        assert_eq!(lifecycle, json!({ "state": "preflight" }));
2999
3000        // A valid header set activates in one atomic step.
3001        dispatch(
3002            &mut transport,
3003            &mut client,
3004            &mut effects,
3005            "activateSecurity",
3006            &json!({ "headers": { "authorization": "Bearer fresh" } }),
3007        )
3008        .expect("activation with fresh headers");
3009        let lifecycle = dispatch(
3010            &mut transport,
3011            &mut client,
3012            &mut effects,
3013            "securityLifecycle",
3014            &json!({}),
3015        )
3016        .expect("lifecycle");
3017        assert_eq!(lifecycle, json!({ "state": "active" }));
3018    }
3019
3020    #[test]
3021    fn parse_headers_reads_the_full_replacement_set() {
3022        let parsed = parse_headers(&json!({
3023            "authorization": "Bearer fresh",
3024            "x-tenant": "t1"
3025        }))
3026        .expect("valid headers parse");
3027        assert_eq!(
3028            parsed,
3029            vec![
3030                ("authorization".to_owned(), "Bearer fresh".to_owned()),
3031                ("x-tenant".to_owned(), "t1".to_owned())
3032            ]
3033        );
3034        assert!(parse_headers(&json!(["authorization"])).is_err());
3035        assert!(parse_headers(&json!({ "authorization": null })).is_err());
3036    }
3037
3038    #[test]
3039    fn set_headers_validates_replacement_and_respects_preflight() {
3040        let mut transport = NoNetwork::default();
3041        let mut client: Option<SyncClient> = None;
3042        let mut effects = CreateEffects::default();
3043        dispatch(
3044            &mut transport,
3045            &mut client,
3046            &mut effects,
3047            "create",
3048            &json!({ "schema": schema() }),
3049        )
3050        .expect("create");
3051        dispatch(
3052            &mut transport,
3053            &mut client,
3054            &mut effects,
3055            "setHeaders",
3056            &json!({ "headers": { "authorization": "Bearer fresh" } }),
3057        )
3058        .expect("valid replacement");
3059        let invalid = dispatch(
3060            &mut transport,
3061            &mut client,
3062            &mut effects,
3063            "setHeaders",
3064            &json!({ "headers": { "authorization": 7 } }),
3065        )
3066        .expect_err("invalid replacement");
3067        assert_eq!(invalid.code, "sync.invalid_request");
3068
3069        dispatch(
3070            &mut transport,
3071            &mut client,
3072            &mut effects,
3073            "beginSecurityPreflight",
3074            &json!({}),
3075        )
3076        .expect("preflight");
3077        let gated = dispatch(
3078            &mut transport,
3079            &mut client,
3080            &mut effects,
3081            "setHeaders",
3082            &json!({ "headers": {} }),
3083        )
3084        .expect_err("direct rotation must respect preflight");
3085        assert_eq!(gated.code, SECURITY_PREFLIGHT_REQUIRED_CODE);
3086    }
3087
3088    fn schema_v2() -> Value {
3089        json!({
3090            "version": 2,
3091            "tables": [{
3092                "name": "todos",
3093                "columns": [
3094                    { "name": "id", "type": "string", "nullable": false },
3095                    { "name": "list_id", "type": "string", "nullable": false },
3096                    { "name": "note", "type": "string", "nullable": true }
3097                ],
3098                "primaryKey": "id",
3099                "scopes": [{ "pattern": "list:{list_id}", "column": "list_id" }]
3100            }]
3101        })
3102    }
3103
3104    fn previous_version_enabled() -> Value {
3105        json!({ "enabled": true })
3106    }
3107
3108    fn container_path(db_path: &str) -> String {
3109        format!("{db_path}.prev-context")
3110    }
3111
3112    #[test]
3113    fn previous_version_config_parser_matches_ts_keys_and_defaults() {
3114        assert_eq!(parse_previous_version_context(None).expect("absent"), None);
3115        let defaults = parse_previous_version_context(Some(&json!({})))
3116            .expect("empty")
3117            .expect("present");
3118        assert!(!defaults.enabled);
3119        assert_eq!(defaults.max_bytes, 8 * 1024 * 1024);
3120        assert_eq!(defaults.max_rows, 20_000);
3121        assert_eq!(defaults.max_tables, 32);
3122        assert_eq!(defaults.max_row_bytes, 1024 * 1024);
3123        assert_eq!(defaults.max_age_ms, 24 * 60 * 60 * 1000);
3124
3125        let configured = parse_previous_version_context(Some(&json!({
3126            "enabled": true,
3127            "maxBytes": 1024,
3128            "maxRows": 3,
3129            "maxTables": 2,
3130            "maxRowBytes": 5,
3131            "maxAgeMs": 7
3132        })))
3133        .expect("configured")
3134        .expect("present");
3135        assert!(configured.enabled);
3136        assert_eq!(configured.max_bytes, 1024);
3137        assert_eq!(configured.max_rows, 3);
3138        assert_eq!(configured.max_tables, 2);
3139        assert_eq!(configured.max_row_bytes, 5);
3140        assert_eq!(configured.max_age_ms, 7);
3141
3142        // Invalid values fail loudly instead of silently defaulting.
3143        for (value, expected) in [
3144            (json!([]), "must be an object"),
3145            (json!({ "enabled": "yes" }), "enabled must be a boolean"),
3146            (
3147                json!({ "maxBytes": 0 }),
3148                "maxBytes must be a positive safe integer",
3149            ),
3150            (
3151                json!({ "maxRows": -1 }),
3152                "maxRows must be a positive safe integer",
3153            ),
3154            (
3155                json!({ "maxTables": 1.5 }),
3156                "maxTables must be a positive safe integer",
3157            ),
3158            (
3159                json!({ "maxRowBytes": "1" }),
3160                "maxRowBytes must be a positive safe integer",
3161            ),
3162            (
3163                json!({ "maxAgeMs": 0 }),
3164                "maxAgeMs must be a positive safe integer",
3165            ),
3166        ] {
3167            let error = parse_previous_version_context(Some(&value)).expect_err("must fail");
3168            assert_eq!(error.code, "sync.invalid_request", "{value}");
3169            assert!(
3170                error.message.contains(expected),
3171                "{value}: {}",
3172                error.message
3173            );
3174        }
3175    }
3176
3177    #[test]
3178    fn invalid_previous_version_config_fails_create_loudly() {
3179        let mut transport = NoNetwork::default();
3180        let mut client: Option<SyncClient> = None;
3181        let mut effects = CreateEffects::default();
3182        let error = dispatch(
3183            &mut transport,
3184            &mut client,
3185            &mut effects,
3186            "create",
3187            &json!({ "schema": schema(), "previousVersionContext": { "enabled": true, "maxRows": 0 } }),
3188        )
3189        .expect_err("invalid config must fail the create");
3190        assert_eq!(error.code, "sync.invalid_request");
3191        assert!(error.message.contains("maxRows"), "{}", error.message);
3192        assert!(client.is_none(), "no client may be installed");
3193    }
3194
3195    #[test]
3196    fn previous_version_snapshot_reports_not_configured_by_default() {
3197        let mut transport = NoNetwork::default();
3198        let mut client: Option<SyncClient> = None;
3199        let mut effects = CreateEffects::default();
3200        dispatch(
3201            &mut transport,
3202            &mut client,
3203            &mut effects,
3204            "create",
3205            &json!({ "schema": schema() }),
3206        )
3207        .expect("create");
3208        let snapshot = dispatch(
3209            &mut transport,
3210            &mut client,
3211            &mut effects,
3212            "previousVersionSnapshot",
3213            &json!({ "table": "todos" }),
3214        )
3215        .expect("snapshot");
3216        assert_eq!(snapshot["state"], json!("previousVersion"));
3217        assert_eq!(snapshot["available"], json!(false));
3218        assert_eq!(snapshot["reason"], json!("not-configured"));
3219        assert_eq!(snapshot["rows"], json!([]));
3220        assert_eq!(snapshot["truncated"], json!(false));
3221        assert_eq!(snapshot["currentVersion"], json!(1));
3222        let discarded = dispatch(
3223            &mut transport,
3224            &mut client,
3225            &mut effects,
3226            "previousVersionDiscard",
3227            &json!({}),
3228        )
3229        .expect("discard");
3230        assert_eq!(discarded, json!({ "present": false, "discarded": false }));
3231        assert_eq!(
3232            dispatch(
3233                &mut transport,
3234                &mut client,
3235                &mut effects,
3236                "previousVersionAudit",
3237                &json!({}),
3238            )
3239            .expect("audit"),
3240            Value::Null
3241        );
3242    }
3243
3244    #[test]
3245    fn previous_version_commands_round_trip_through_the_dispatcher() {
3246        let path = temp_db_path("previous-version");
3247        let mut transport = NoNetwork::default();
3248        let mut client: Option<SyncClient> = None;
3249        let mut effects = CreateEffects::default();
3250
3251        // A v1 replica with one pending local row and the feature on.
3252        dispatch(
3253            &mut transport,
3254            &mut client,
3255            &mut effects,
3256            "create",
3257            &json!({
3258                "schema": schema(),
3259                "dbPath": path,
3260                "previousVersionContext": previous_version_enabled()
3261            }),
3262        )
3263        .expect("create v1");
3264        client
3265            .as_mut()
3266            .expect("client")
3267            .mutate(vec![Mutation::Upsert {
3268                table: "todos".to_owned(),
3269                values: serde_json::Map::from_iter([
3270                    ("id".to_owned(), json!("t1")),
3271                    ("list_id".to_owned(), json!("l1")),
3272                ]),
3273                base_version: None,
3274            }])
3275            .expect("seed a local row");
3276        dispatch(
3277            &mut transport,
3278            &mut client,
3279            &mut effects,
3280            "shutdown",
3281            &json!({}),
3282        )
3283        .expect("shutdown");
3284
3285        // The bump captures into the sibling file.
3286        dispatch(
3287            &mut transport,
3288            &mut client,
3289            &mut effects,
3290            "create",
3291            &json!({
3292                "schema": schema_v2(),
3293                "dbPath": path,
3294                "previousVersionContext": previous_version_enabled()
3295            }),
3296        )
3297        .expect("create v2");
3298        assert!(
3299            std::path::Path::new(&container_path(&path)).exists(),
3300            "the bump must leave a container file"
3301        );
3302        let status = dispatch(
3303            &mut transport,
3304            &mut client,
3305            &mut effects,
3306            "statusSnapshot",
3307            &json!({}),
3308        )
3309        .expect("status");
3310        assert_eq!(
3311            status["previousVersionContext"]["present"],
3312            json!(true),
3313            "{status}"
3314        );
3315        assert!(
3316            status["previousVersionContext"]["createdAtMs"].is_i64(),
3317            "{status}"
3318        );
3319
3320        let snapshot = dispatch(
3321            &mut transport,
3322            &mut client,
3323            &mut effects,
3324            "previousVersionSnapshot",
3325            &json!({ "table": "todos" }),
3326        )
3327        .expect("snapshot");
3328        assert_eq!(snapshot["state"], json!("previousVersion"));
3329        assert_eq!(snapshot["available"], json!(true));
3330        assert_eq!(snapshot["previousVersion"], json!(1));
3331        assert_eq!(snapshot["currentVersion"], json!(2));
3332        assert_eq!(snapshot["truncated"], json!(false));
3333        assert_eq!(snapshot["rows"][0]["id"], json!("t1"));
3334        assert_eq!(snapshot["rows"][0]["list_id"], json!("l1"));
3335
3336        // Unknown previous table and a bad limit are loud request errors.
3337        let unknown = dispatch(
3338            &mut transport,
3339            &mut client,
3340            &mut effects,
3341            "previousVersionSnapshot",
3342            &json!({ "table": "absent" }),
3343        )
3344        .expect_err("unknown previous table");
3345        assert_eq!(unknown.code, "sync.invalid_request");
3346        let bad_limit = dispatch(
3347            &mut transport,
3348            &mut client,
3349            &mut effects,
3350            "previousVersionSnapshot",
3351            &json!({ "table": "todos", "limit": 0 }),
3352        )
3353        .expect_err("bad limit");
3354        assert_eq!(bad_limit.code, "sync.invalid_request");
3355
3356        // D6: the audit names the pending commit's classification, with no
3357        // envelope and nothing dropped.
3358        let audit = dispatch(
3359            &mut transport,
3360            &mut client,
3361            &mut effects,
3362            "previousVersionAudit",
3363            &json!({}),
3364        )
3365        .expect("audit");
3366        assert_eq!(audit["v"], json!(1));
3367        assert_eq!(audit["fromVersion"], json!(1));
3368        assert_eq!(audit["toVersion"], json!(2));
3369        assert_eq!(audit["pending"], json!(1));
3370        assert_eq!(audit["encodable"], json!(1));
3371        assert_eq!(audit["incompatible"], json!([]));
3372        assert!(audit.get("operations").is_none());
3373
3374        // The executable downgrade step, idempotent.
3375        let discarded = dispatch(
3376            &mut transport,
3377            &mut client,
3378            &mut effects,
3379            "previousVersionDiscard",
3380            &json!({}),
3381        )
3382        .expect("discard");
3383        assert_eq!(discarded, json!({ "present": true, "discarded": true }));
3384        assert!(!std::path::Path::new(&container_path(&path)).exists());
3385        let again = dispatch(
3386            &mut transport,
3387            &mut client,
3388            &mut effects,
3389            "previousVersionDiscard",
3390            &json!({}),
3391        )
3392        .expect("idempotent discard");
3393        assert_eq!(again, json!({ "present": false, "discarded": false }));
3394
3395        // Storage read directly: both metadata records are gone.
3396        let inspect = rusqlite::Connection::open(&path).expect("inspect replica");
3397        let remaining: i64 = inspect
3398            .query_row(
3399                "SELECT COUNT(*) FROM _syncular_meta WHERE key IN (?1, ?2)",
3400                rusqlite::params!["previousVersionContext", "previousVersionAudit"],
3401                |row| row.get(0),
3402            )
3403            .expect("count meta");
3404        assert_eq!(remaining, 0);
3405
3406        let _ = std::fs::remove_file(&path);
3407    }
3408
3409    #[test]
3410    fn previous_version_ttl_expires_at_read_through_the_dispatcher() {
3411        let path = temp_db_path("previous-version-ttl");
3412        let mut transport = NoNetwork::default();
3413        let mut client: Option<SyncClient> = None;
3414        let mut effects = CreateEffects::default();
3415        dispatch(
3416            &mut transport,
3417            &mut client,
3418            &mut effects,
3419            "create",
3420            &json!({
3421                "schema": schema(),
3422                "dbPath": path,
3423                "previousVersionContext": previous_version_enabled()
3424            }),
3425        )
3426        .expect("create v1");
3427        dispatch(
3428            &mut transport,
3429            &mut client,
3430            &mut effects,
3431            "shutdown",
3432            &json!({}),
3433        )
3434        .expect("shutdown");
3435
3436        // The injected clock is two seconds past the capture, with a TTL far
3437        // larger than the boot gap but far smaller than the skew, so the boot
3438        // reconcile keeps the container and the read expires it.
3439        let now_ms = std::time::SystemTime::now()
3440            .duration_since(std::time::UNIX_EPOCH)
3441            .expect("clock")
3442            .as_millis() as i64
3443            + 2_000;
3444        dispatch(
3445            &mut transport,
3446            &mut client,
3447            &mut effects,
3448            "create",
3449            &json!({
3450                "schema": schema_v2(),
3451                "dbPath": path,
3452                "nowMs": now_ms,
3453                "previousVersionContext": { "enabled": true, "maxAgeMs": 500 }
3454            }),
3455        )
3456        .expect("create v2");
3457        assert!(std::path::Path::new(&container_path(&path)).exists());
3458        let snapshot = dispatch(
3459            &mut transport,
3460            &mut client,
3461            &mut effects,
3462            "previousVersionSnapshot",
3463            &json!({ "table": "todos" }),
3464        )
3465        .expect("snapshot");
3466        assert_eq!(snapshot["available"], json!(false));
3467        assert_eq!(snapshot["reason"], json!("expired"));
3468        assert_eq!(snapshot["rows"], json!([]));
3469        // The TTL discards, and the FILE is what must be gone.
3470        assert!(!std::path::Path::new(&container_path(&path)).exists());
3471
3472        let _ = std::fs::remove_file(&path);
3473    }
3474}