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