Skip to main content

second_brain_sync/
protocol.rs

1use std::fmt;
2use std::io::BufRead;
3
4use anyhow::{Context, Result};
5use base64::Engine;
6use base64::engine::general_purpose::URL_SAFE_NO_PAD;
7use second_brain_core::keys::{
8    DeviceRoute, Envelope, Epoch, EpochCause, IdentityTag, SignedRecord, SignedRetirement,
9    SignedRevocation,
10};
11use second_brain_core::sqlite_store::{SCHEMA_VERSION, SqliteStore};
12use serde::{Deserialize, Serialize};
13
14/// Bump whenever the sync wire format or the meaning of a field changes:
15/// the record envelope, the header line, the line framing or the crypto frame.
16/// `wire_format_matches_the_protocol_version` pins the current format.
17/// Releases up to second-brain 0.10.0 sent no header and count as protocol 1.
18pub const SYNC_PROTOCOL_VERSION: u32 = 9;
19
20const UNVERSIONED_PROTOCOL: u32 = 1;
21
22/// Makes the header line neither base64 nor JSON: binaries up to 0.10.0 pass
23/// any non-base64 line through as a plaintext JSON record, and only a parse
24/// failure on the first line stops them before they apply anything.
25const HEADER_PREFIX: &str = "second-brain-sync";
26
27/// First line of every sync stream: `HEADER_PREFIX`, a space, then plaintext
28/// JSON, so a peer holding the wrong key still gets a version error. It carries
29/// no data, is not a change-log entry and has no sequence number.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
31pub struct SyncHeader {
32    pub sync_protocol: u32,
33    /// `PRAGMA user_version` of the store whose records the stream carries.
34    pub schema_version: i64,
35    /// The sender's clock handshake; `ensure_matches` ignores it.
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    pub hello: Option<Hello>,
38}
39
40/// What each side of a sync tells the other about its clock and how much of
41/// the other's log it holds, so neither reissues a sequence number or an
42/// origin key the other has already seen.
43#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
44pub struct Hello {
45    pub machine_id: String,
46    /// Microseconds since the Unix epoch.
47    pub wall_micros: i64,
48    /// The sender's clock is NTP-synchronised: the signal itself, not merely
49    /// a clock gate that has opened.
50    pub synced: bool,
51    /// The sender's cursor on the receiver's log.
52    pub cursor: Option<u64>,
53    /// The highest origin_seq of the receiver's own records the sender holds.
54    pub held_origin_seq: Option<i64>,
55    /// None from a sender on sync protocol 3 or older.
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub keys: Option<HandshakeKeys>,
58    /// The highest seq of the receiver's log that the receiver's pushes into
59    /// the sender have applied.
60    #[serde(default)]
61    pub peer_in: Option<u64>,
62    /// The sender's log holds no rows at or below this seq.
63    #[serde(default)]
64    pub log_floor: u64,
65    /// The highest seq the sender has minted.
66    #[serde(default)]
67    pub head: u64,
68    /// How far into the receiver's log the sender has applied without a
69    /// gap, below `cursor` while a record from it still fails.
70    #[serde(default)]
71    pub applied: Option<u64>,
72    /// A snapshot merge the sender has not finished; a pusher neither
73    /// streams another nor advances while one runs.
74    #[serde(default)]
75    pub merging: Option<Merging>,
76}
77
78#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
79pub struct Merging {
80    pub snapshot_id: String,
81    pub exporter: String,
82    /// `S`, the seq the snapshot is consistent at.
83    pub seq: u64,
84}
85
86/// The line `sb sync-export` writes instead of a header when the exporter's
87/// log no longer holds the rows after the puller's cursor, so the puller
88/// merges a snapshot.
89const BELOW_FLOOR_PREFIX: &str = "second-brain-sync-below-floor";
90
91#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
92pub struct BelowFloorLine {
93    pub after_seq: u64,
94    pub log_floor: u64,
95}
96
97impl BelowFloorLine {
98    pub fn to_line(&self) -> String {
99        format!(
100            "{BELOW_FLOOR_PREFIX} {}",
101            serde_json::to_string(self).expect("BelowFloorLine serializes")
102        )
103    }
104
105    pub fn parse_line(line: &str) -> Option<Self> {
106        let json = line.trim().strip_prefix(BELOW_FLOOR_PREFIX)?;
107        serde_json::from_str(json.trim()).ok()
108    }
109}
110
111/// The line a peer writes instead of a header or a push reply when its daemon
112/// refuses the sync, so the initiator gets the peer's own error rather than
113/// only its exit status.
114const REFUSED_PREFIX: &str = "second-brain-sync-refused";
115
116#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
117pub struct RefusedLine {
118    pub error: String,
119    #[serde(default)]
120    pub identity: bool,
121}
122
123impl RefusedLine {
124    pub fn to_line(&self) -> String {
125        format!(
126            "{REFUSED_PREFIX} {}",
127            serde_json::to_string(self).expect("RefusedLine serializes")
128        )
129    }
130
131    pub fn parse_line(line: &str) -> Option<Self> {
132        let json = line.trim().strip_prefix(REFUSED_PREFIX)?;
133        serde_json::from_str(json.trim()).ok()
134    }
135
136    /// A daemon's 409 body, unless it asks for a snapshot or a wait instead.
137    pub fn from_refusal_body(body: &str) -> Option<Self> {
138        let value: serde_json::Value = serde_json::from_str(body).ok()?;
139        if value["below_floor"] == true || value["merging"] == true {
140            return None;
141        }
142        Some(Self {
143            error: value["error"].as_str()?.to_string(),
144            identity: value["identity"] == true,
145        })
146    }
147}
148
149/// The sender's sync identity, carried in plaintext: nothing here is secret,
150/// since envelopes are sealed to their recipient and rows are signed.
151#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
152pub struct HandshakeKeys {
153    /// None when the sender holds no identity key yet.
154    pub identity_tag: Option<IdentityTag>,
155    /// Every epoch of `identity_tag` the sender can open.
156    #[serde(default)]
157    pub epochs: Vec<Epoch>,
158    /// The signed device rows of `identity_tag` the sender holds.
159    #[serde(default)]
160    pub devices: Vec<SignedRecord>,
161    /// Epochs the sender wrapped for the receiver.
162    #[serde(default)]
163    pub envelopes: Vec<Envelope>,
164    /// The revocations of `identity_tag` the sender holds.
165    #[serde(default, skip_serializing_if = "Vec::is_empty")]
166    pub revocations: Vec<SignedRevocation>,
167    /// The recovery phrase retirements of `identity_tag` the sender holds.
168    #[serde(default, skip_serializing_if = "Vec::is_empty")]
169    pub retirements: Vec<SignedRetirement>,
170    /// The revocations behind each epoch in `epochs` that has any; an
171    /// envelope is taken only once its epoch's revocations are applied.
172    #[serde(default, skip_serializing_if = "Vec::is_empty")]
173    pub causes: Vec<(Epoch, EpochCause)>,
174    /// How to reach the sender and the active devices it knows; unsigned
175    /// hints, since host keys are pinned per machine id.
176    #[serde(default, skip_serializing_if = "Vec::is_empty")]
177    pub routes: Vec<DeviceRoute>,
178}
179
180impl Hello {
181    /// How far into the receiver's log the sender has applied, by its own
182    /// pulls or by the receiver's pushes.
183    pub fn applied_of_receiver(&self) -> Option<u64> {
184        self.cursor.max(self.peer_in)
185    }
186
187    /// `applied_of_receiver` without the gaps: a record the sender still
188    /// fails to apply holds this below its cursor, so the floor keeps it.
189    pub fn acked_by_receiver(&self) -> Option<u64> {
190        self.applied.or(self.cursor).max(self.peer_in)
191    }
192
193    /// One shell word, for `sb sync-export --hello` over ssh.
194    pub fn to_arg(&self) -> String {
195        URL_SAFE_NO_PAD.encode(serde_json::to_vec(self).expect("Hello serializes"))
196    }
197
198    /// Refuses a hello from a binary that predates sync identities, naming
199    /// the upgrade rather than pairing as the fix.
200    pub fn keys(&self) -> Result<&HandshakeKeys, VersionError> {
201        self.keys
202            .as_ref()
203            .ok_or_else(|| VersionError::KeylessHello {
204                peer: self.machine_id.clone(),
205            })
206    }
207
208    pub fn from_arg(arg: &str) -> Result<Self> {
209        let json = URL_SAFE_NO_PAD
210            .decode(arg.trim())
211            .context("decoding the sync hello")?;
212        serde_json::from_slice(&json).context("parsing the sync hello")
213    }
214}
215
216/// The last line `sb sync-import` writes back to the pusher: the highest seq
217/// of the pusher's log it applied without a gap.
218#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
219pub struct PushApplied {
220    pub applied: u64,
221}
222
223impl PushApplied {
224    pub fn to_line(&self) -> String {
225        serde_json::to_string(self).expect("PushApplied serializes")
226    }
227
228    pub fn parse_line(line: &str) -> Result<Self> {
229        serde_json::from_str(line.trim()).context("parsing the push result line")
230    }
231}
232
233impl SyncHeader {
234    pub fn current(schema_version: i64) -> Self {
235        Self {
236            sync_protocol: SYNC_PROTOCOL_VERSION,
237            schema_version,
238            hello: None,
239        }
240    }
241
242    /// The versions this binary was built with.
243    pub fn local() -> Self {
244        Self::current(SCHEMA_VERSION)
245    }
246
247    pub fn to_line(&self) -> String {
248        let json = serde_json::to_string(self).expect("SyncHeader serializes");
249        format!("{HEADER_PREFIX} {json}")
250    }
251
252    pub fn parse_line(line: &str) -> Result<Self, VersionError> {
253        line.trim()
254            .strip_prefix(HEADER_PREFIX)
255            .and_then(|rest| serde_json::from_str(rest).ok())
256            .ok_or(VersionError::MissingHeader)
257    }
258
259    /// Refuses unless both sides speak the same protocol over the same schema.
260    /// `local_name` and `peer_name` name the two sides in the error message.
261    pub fn ensure_matches(
262        &self,
263        local_name: &str,
264        peer: &Self,
265        peer_name: &str,
266    ) -> Result<(), VersionError> {
267        if (self.sync_protocol, self.schema_version) == (peer.sync_protocol, peer.schema_version) {
268            return Ok(());
269        }
270        Err(VersionError::Mismatch {
271            local: self.clone(),
272            local_name: local_name.to_string(),
273            peer: peer.clone(),
274            peer_name: peer_name.to_string(),
275        })
276    }
277}
278
279#[derive(Debug, Clone, PartialEq, Eq)]
280pub enum VersionError {
281    /// A stream or request without a header: its sender predates versioning.
282    MissingHeader,
283    /// The local daemon has no version route: it predates versioning.
284    UnversionedDaemon,
285    /// A hello without a sync identity: its sender predates them.
286    KeylessHello { peer: String },
287    Mismatch {
288        local: SyncHeader,
289        local_name: String,
290        peer: SyncHeader,
291        peer_name: String,
292    },
293}
294
295impl fmt::Display for VersionError {
296    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
297        match self {
298            VersionError::MissingHeader => write_unversioned(f, "the sender"),
299            VersionError::UnversionedDaemon => write_unversioned(f, "the local daemon"),
300            VersionError::KeylessHello { peer } => write!(
301                f,
302                "{peer} sent a sync hello without a sync identity, so it speaks sync protocol 3 \
303                 or older and this side speaks protocol {SYNC_PROTOCOL_VERSION}; upgrade {peer}, \
304                 nothing was applied"
305            ),
306            VersionError::Mismatch {
307                local,
308                local_name,
309                peer,
310                peer_name,
311            } => {
312                let older = if (local.sync_protocol, local.schema_version)
313                    < (peer.sync_protocol, peer.schema_version)
314                {
315                    local_name
316                } else {
317                    peer_name
318                };
319                write!(
320                    f,
321                    "sync version mismatch: {local_name} has sync protocol {} and schema {}, \
322                     {peer_name} has sync protocol {} and schema {}; upgrade {older}, \
323                     nothing was applied",
324                    local.sync_protocol,
325                    local.schema_version,
326                    peer.sync_protocol,
327                    peer.schema_version
328                )
329            }
330        }
331    }
332}
333
334fn write_unversioned(f: &mut fmt::Formatter<'_>, side: &str) -> fmt::Result {
335    write!(
336        f,
337        "{side} declared no sync version, so it speaks sync protocol {UNVERSIONED_PROTOCOL} \
338         (second-brain 0.10.0 or older) and this side speaks protocol {SYNC_PROTOCOL_VERSION}; \
339         upgrade {side}, nothing was applied"
340    )
341}
342
343impl std::error::Error for VersionError {}
344
345/// Reads the header line that must open a sync stream, skipping blank lines.
346/// An empty stream is refused like a header-less one: a current sender always
347/// writes the header, even when it has no records.
348pub fn read_header<R: BufRead>(reader: &mut R) -> Result<SyncHeader> {
349    let mut line = String::new();
350    loop {
351        line.clear();
352        if reader
353            .read_line(&mut line)
354            .context("reading sync stream header")?
355            == 0
356        {
357            return Err(VersionError::MissingHeader.into());
358        }
359        if !line.trim().is_empty() {
360            return Ok(SyncHeader::parse_line(&line)?);
361        }
362    }
363}
364
365/// The versions this daemon syncs at. A binary older than the database it
366/// serves is refused, because applying records it would drop the columns it
367/// does not know.
368pub fn store_header(sqlite: &SqliteStore) -> Result<SyncHeader> {
369    let store = SyncHeader::current(sqlite.schema_version()?);
370    SyncHeader::current(SCHEMA_VERSION).ensure_matches(
371        "this daemon's binary",
372        &store,
373        "its database",
374    )?;
375    Ok(store)
376}
377
378pub fn check_store_header(
379    sqlite: &SqliteStore,
380    declared: Option<&SyncHeader>,
381    sender: &str,
382) -> Result<()> {
383    let ours = store_header(sqlite)?;
384    let theirs = declared.ok_or(VersionError::MissingHeader)?;
385    ours.ensure_matches("this daemon", theirs, sender)?;
386    Ok(())
387}
388
389#[cfg(test)]
390mod tests {
391    use std::io::BufReader;
392
393    use base64::Engine;
394    use base64::engine::general_purpose::STANDARD as B64;
395    use chrono::{TimeZone, Utc};
396    use second_brain_core::keys::DeviceRecord;
397    use second_brain_core::schema::{SyncNodeType, SyncOp, SyncRecord};
398
399    use super::*;
400    use crate::crypto::{XChaChaEncryptor, seal_line};
401
402    fn header(protocol: u32, schema: i64) -> SyncHeader {
403        SyncHeader {
404            sync_protocol: protocol,
405            schema_version: schema,
406            hello: None,
407        }
408    }
409
410    #[test]
411    fn header_line_round_trips() {
412        let h = SyncHeader::current(7);
413        let line = h.to_line();
414        assert!(!line.contains('\n'));
415        assert_eq!(SyncHeader::parse_line(&line).unwrap(), h);
416    }
417
418    #[test]
419    fn header_line_aborts_an_unversioned_reader() {
420        let line = SyncHeader::current(7).to_line();
421        assert!(
422            serde_json::from_str::<serde_json::Value>(&line).is_err(),
423            "{line}"
424        );
425        assert!(B64.decode(line.trim()).is_err(), "{line}");
426    }
427
428    #[test]
429    fn read_header_consumes_only_the_header_line() {
430        let enc = XChaChaEncryptor::new([3; 32]);
431        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
432        let stream = format!("\n{}\n{record}\n", SyncHeader::current(7).to_line());
433        let mut reader = BufReader::new(stream.as_bytes());
434        assert_eq!(read_header(&mut reader).unwrap(), SyncHeader::current(7));
435        let rest: Vec<String> = reader.lines().map(|l| l.unwrap()).collect();
436        assert_eq!(
437            rest,
438            vec![record],
439            "records after the header are left unread"
440        );
441    }
442
443    #[test]
444    fn stream_starting_with_a_record_has_no_header() {
445        let enc = XChaChaEncryptor::new([3; 32]);
446        let record = seal_line(&enc, b"{\"local_seq\":1}").unwrap();
447        let stream = format!("{record}\n");
448        let mut reader = BufReader::new(stream.as_bytes());
449        let err = read_header(&mut reader).unwrap_err();
450        assert_eq!(
451            err.downcast_ref::<VersionError>(),
452            Some(&VersionError::MissingHeader)
453        );
454        assert!(err.to_string().contains("protocol 1"), "{err}");
455    }
456
457    #[test]
458    fn legacy_plaintext_record_is_not_a_header() {
459        let legacy = r#"{"local_seq":1,"origin_machine_id":"m","origin_seq":1,"op":"create","node_type":"memory","node_id":"x","timestamp":"2026-01-01T00:00:00Z","data":null}"#;
460        assert_eq!(
461            SyncHeader::parse_line(legacy),
462            Err(VersionError::MissingHeader)
463        );
464    }
465
466    #[test]
467    fn empty_stream_has_no_header() {
468        let mut reader = BufReader::new(&b""[..]);
469        let err = read_header(&mut reader).unwrap_err();
470        assert_eq!(
471            err.downcast_ref::<VersionError>(),
472            Some(&VersionError::MissingHeader)
473        );
474    }
475
476    #[test]
477    fn matching_headers_pass() {
478        let h = SyncHeader::current(7);
479        assert!(h.ensure_matches("this machine", &h, "peer").is_ok());
480    }
481
482    fn sample_hello() -> Hello {
483        Hello {
484            machine_id: "m".to_string(),
485            wall_micros: 1_767_225_600_000_000,
486            synced: true,
487            cursor: Some(5),
488            held_origin_seq: Some((1 << 32) | 1),
489            keys: Some(HandshakeKeys {
490                identity_tag: Some(IdentityTag::from("m-0001020304050607".to_string())),
491                epochs: vec![Epoch {
492                    number: 1,
493                    key_id: "08090a0b0c0d0e0f".parse().unwrap(),
494                }],
495                devices: vec![sample_row()],
496                envelopes: vec![Envelope {
497                    identity_tag: IdentityTag::from("m-0001020304050607".to_string()),
498                    epoch: Epoch {
499                        number: 1,
500                        key_id: "08090a0b0c0d0e0f".parse().unwrap(),
501                    },
502                    recipient: "age1recipient".to_string(),
503                    machine_id: Some("m".to_string()),
504                    ciphertext: vec![1, 2, 3],
505                }],
506                revocations: Vec::new(),
507                retirements: Vec::new(),
508                causes: Vec::new(),
509                routes: Vec::new(),
510            }),
511            peer_in: Some(3),
512            log_floor: 2,
513            head: 9,
514            applied: None,
515            merging: None,
516        }
517    }
518
519    fn sample_row() -> SignedRecord {
520        let key = ed25519_dalek::SigningKey::from_bytes(&[1; 32]);
521        DeviceRecord {
522            machine_id: "m".to_string(),
523            identity_tag: "m-0001020304050607".to_string(),
524            version: 1,
525            name: "n".to_string(),
526            age_recipient: "age1recipient".to_string(),
527            ssh_public_key: "ssh-ed25519 AAAA".to_string(),
528            signing_public_key: key.verifying_key().to_bytes(),
529            recovery_fingerprints: vec!["fp".to_string()],
530            ssh_login: Some("user".to_string()),
531            ssh_port: Some(22),
532            ssh_host_key: Some("ssh-ed25519 BBBB".to_string()),
533        }
534        .sign("m", &key)
535    }
536
537    fn with_hello(schema: i64) -> SyncHeader {
538        SyncHeader {
539            hello: Some(sample_hello()),
540            ..SyncHeader::current(schema)
541        }
542    }
543
544    #[test]
545    fn header_line_with_a_hello_round_trips() {
546        let h = with_hello(7);
547        let line = h.to_line();
548        assert!(!line.contains('\n'));
549        assert_eq!(SyncHeader::parse_line(&line).unwrap(), h);
550    }
551
552    #[test]
553    fn header_line_without_a_hello_omits_it() {
554        let line = SyncHeader::current(7).to_line();
555        assert!(!line.contains("hello"), "{line}");
556        assert_eq!(SyncHeader::parse_line(&line).unwrap().hello, None);
557    }
558
559    #[test]
560    fn ensure_matches_ignores_the_hello() {
561        let bare = SyncHeader::current(7);
562        let greeted = with_hello(7);
563        assert!(
564            bare.ensure_matches("this machine", &greeted, "peer")
565                .is_ok()
566        );
567        assert!(
568            greeted
569                .ensure_matches("this machine", &bare, "peer")
570                .is_ok()
571        );
572        assert!(
573            with_hello(8)
574                .ensure_matches("this machine", &greeted, "peer")
575                .is_err()
576        );
577    }
578
579    #[test]
580    fn a_hello_from_before_sync_identities_asks_for_an_upgrade_not_pairing() {
581        let old = r#"{"machine_id":"mac","wall_micros":1,"synced":false,"cursor":null,"held_origin_seq":null}"#;
582        let hello: Hello = serde_json::from_str(old).unwrap();
583        let err = hello.keys().unwrap_err().to_string();
584        assert!(err.contains("upgrade mac"), "{err}");
585        assert!(!err.contains("pair"), "{err}");
586        assert!(sample_hello().keys().is_ok());
587    }
588
589    #[test]
590    fn hello_argument_round_trips_in_one_shell_word() {
591        let hello = sample_hello();
592        let arg = hello.to_arg();
593        assert!(
594            arg.chars()
595                .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'),
596            "{arg}"
597        );
598        assert_eq!(Hello::from_arg(&arg).unwrap(), hello);
599        assert!(Hello::from_arg("not a hello").is_err());
600    }
601
602    #[test]
603    fn protocol_mismatch_names_both_versions_and_the_older_side() {
604        let err = header(2, 7)
605            .ensure_matches("this machine", &header(3, 7), "pi")
606            .unwrap_err()
607            .to_string();
608        assert!(
609            err.contains("this machine has sync protocol 2 and schema 7"),
610            "{err}"
611        );
612        assert!(err.contains("pi has sync protocol 3 and schema 7"), "{err}");
613        assert!(err.contains("upgrade this machine"), "{err}");
614    }
615
616    #[test]
617    fn schema_mismatch_names_the_older_side() {
618        let err = header(2, 8)
619            .ensure_matches("this machine", &header(2, 7), "pi")
620            .unwrap_err()
621            .to_string();
622        assert!(
623            err.contains("schema 8") && err.contains("schema 7"),
624            "{err}"
625        );
626        assert!(err.contains("upgrade pi"), "{err}");
627    }
628
629    fn every_op() -> Vec<SyncOp> {
630        let ops = vec![SyncOp::Create, SyncOp::Update, SyncOp::Delete];
631        for op in &ops {
632            match op {
633                SyncOp::Create | SyncOp::Update | SyncOp::Delete => {}
634            }
635        }
636        ops
637    }
638
639    fn every_node_type() -> Vec<SyncNodeType> {
640        let types = vec![
641            SyncNodeType::Memory,
642            SyncNodeType::Entity,
643            SyncNodeType::Conversation,
644            SyncNodeType::Relation,
645            SyncNodeType::Distillation,
646        ];
647        for t in &types {
648            match t {
649                SyncNodeType::Memory
650                | SyncNodeType::Entity
651                | SyncNodeType::Conversation
652                | SyncNodeType::Relation
653                | SyncNodeType::Distillation => {}
654            }
655        }
656        types
657    }
658
659    fn wire_format() -> String {
660        let record = SyncRecord {
661            local_seq: 1,
662            origin_machine_id: "m".to_string(),
663            origin_seq: 2,
664            op: SyncOp::Create,
665            node_type: SyncNodeType::Memory,
666            node_id: "n".to_string(),
667            timestamp: Utc.with_ymd_and_hms(2026, 1, 2, 3, 4, 5).unwrap(),
668            data: Some(serde_json::json!({"k": "v"})),
669        };
670        let ops: Vec<String> = every_op()
671            .iter()
672            .map(|o| serde_json::to_string(o).unwrap())
673            .collect();
674        let types: Vec<String> = every_node_type()
675            .iter()
676            .map(|t| serde_json::to_string(t).unwrap())
677            .collect();
678        format!(
679            "header={}\nhello_header={}\npush_applied={}\nrecord={}\nops={}\nnode_types={}\nframe={}\nbelow_floor={}\nrefused={}\nsnapshot={}",
680            SyncHeader::current(7).to_line(),
681            with_hello(7).to_line(),
682            PushApplied { applied: 4 }.to_line(),
683            serde_json::to_string(&record).unwrap(),
684            ops.join(","),
685            types.join(","),
686            crate::crypto::frame_format(),
687            BelowFloorLine {
688                after_seq: 1,
689                log_floor: 2
690            }
691            .to_line(),
692            RefusedLine {
693                error: "e".into(),
694                identity: true
695            }
696            .to_line(),
697            crate::snapshot::snapshot_format(),
698        )
699    }
700
701    #[test]
702    fn refused_line_round_trips_and_is_not_a_header() {
703        let refused = RefusedLine {
704            error: "machine-b holds a different sync identity; run `sb pair`".into(),
705            identity: true,
706        };
707        let line = refused.to_line();
708        assert_eq!(RefusedLine::parse_line(&line), Some(refused));
709        assert!(SyncHeader::parse_line(&line).is_err());
710        assert_eq!(BelowFloorLine::parse_line(&line), None);
711        assert_eq!(
712            RefusedLine::parse_line(&SyncHeader::local().to_line()),
713            None
714        );
715    }
716
717    #[test]
718    fn a_refusal_body_reads_its_error_and_identity_flag() {
719        assert_eq!(
720            RefusedLine::from_refusal_body(r#"{"error":"run `sb pair`","identity":true}"#),
721            Some(RefusedLine {
722                error: "run `sb pair`".into(),
723                identity: true
724            })
725        );
726        assert_eq!(
727            RefusedLine::from_refusal_body(r#"{"error":"sync version mismatch"}"#),
728            Some(RefusedLine {
729                error: "sync version mismatch".into(),
730                identity: false
731            })
732        );
733    }
734
735    #[test]
736    fn a_refusal_body_asking_for_a_snapshot_or_a_wait_is_not_a_refusal() {
737        for body in [
738            r#"{"error":"below","below_floor":true,"after_seq":1,"log_floor":2}"#,
739            r#"{"error":"merging","merging":true,"snapshot":{}}"#,
740            r#"{"error":7}"#,
741            r#"{"message":"no error field"}"#,
742            "not json",
743        ] {
744            assert_eq!(RefusedLine::from_refusal_body(body), None, "{body}");
745        }
746    }
747
748    #[test]
749    fn wire_format_matches_the_protocol_version() {
750        const PINNED: (u32, &str) = (
751            9,
752            "header=second-brain-sync {\"sync_protocol\":9,\"schema_version\":7}\n\
753             hello_header=second-brain-sync {\"sync_protocol\":9,\"schema_version\":7,\"hello\
754             \":{\"machine_id\":\"m\",\"wall_micros\":1767225600000000,\"synced\":true,\"curs\
755             or\":5,\"held_origin_seq\":4294967297,\"keys\":{\"identity_tag\":\"m-00010203040\
756             50607\",\"epochs\":[{\"number\":1,\"key_id\":\"08090a0b0c0d0e0f\"}],\"devices\":\
757             [{\"record\":{\"machine_id\":\"m\",\"identity_tag\":\"m-0001020304050607\",\"ver\
758             sion\":1,\"name\":\"n\",\"age_recipient\":\"age1recipient\",\"ssh_public_key\":\"\
759             ssh-ed25519 AAAA\",\"signing_public_key\":\"8a88e3dd7409f195fd52db2d3cba5d72ca67\
760             09bf1d94121bf3748801b40f6f5c\",\"recovery_fingerprints\":[\"fp\"],\"ssh_login\":\
761             \"user\",\"ssh_port\":22,\"ssh_host_key\":\"ssh-ed25519 BBBB\"},\"signatures\":[\
762             {\"signer\":\"m\",\"signature\":\"2db3155897e491f055ffdba51499bd9f272db9f0c4ff20\
763             134883805b167ca8257a583705b6613ad5649f4cc23cab8a495630b1b8e279f17967257ba14a6c2f\
764             0d\"}]}],\"envelopes\":[{\"identity_tag\":\"m-0001020304050607\",\"epoch\":{\"nu\
765             mber\":1,\"key_id\":\"08090a0b0c0d0e0f\"},\"recipient\":\"age1recipient\",\"mach\
766             ine_id\":\"m\",\"ciphertext\":[1,2,3]}]},\"peer_in\":3,\"log_floor\":2,\"head\":9,\"applied\":null,\"mergin\
767             g\":null}}\n\
768             push_applied={\"applied\":4}\n\
769             record={\"local_seq\":1,\"origin_machine_id\":\"m\",\"origin_seq\":2,\"op\":\"create\",\
770             \"node_type\":\"memory\",\"node_id\":\"n\",\"timestamp\":\"2026-01-02T03:04:05Z\",\
771             \"data\":{\"k\":\"v\"}}\n\
772             ops=\"create\",\"update\",\"delete\"\n\
773             node_types=\"memory\",\"entity\",\"conversation\",\"relation\",\"distillation\"\n\
774             frame=base64(0x02 | epoch u32 be | key id[8] | nonce[24] | xchacha20poly1305 \
775             ciphertext, aad = first 13 bytes)\n\
776             below_floor=second-brain-sync-below-floor {\"after_seq\":1,\"log_floor\":2}\n\
777             refused=second-brain-sync-refused {\"error\":\"e\",\"identity\":true}\n\
778             snapshot=second-brain-snapshot <json header> \\n, then frames of kind u8 (1 rows, 2 \
779             manifest) | len u32 be | nonce[24] | xchacha20poly1305(zstd(jsonl rows) or json \
780             manifest), aad = \"second-brain snapshot frame v1\" | epoch u32 be | key id[8] | \
781             snapshot id | kind | frame index u64 be",
782        );
783        assert_eq!(
784            (SYNC_PROTOCOL_VERSION, wire_format().as_str()),
785            PINNED,
786            "the sync wire format changed: bump SYNC_PROTOCOL_VERSION and re-pin this test"
787        );
788    }
789}