memstead-base 0.3.0

Engine internals for Memstead — store, parser, validators, filesystem-mem engine. Internal library surface consumed by the memstead binaries — pre-1.0, experimental, no API stability promise.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Per-commit wire envelope and entity-change variants.
//!
//! Engine-owned value types in the `memstead-base::ops` family
//! (sibling to [`Diff`](crate::ops::Diff),
//! [`ChangeEnvelope`](crate::ops::ChangeEnvelope),
//! [`MemChangedEvent`](crate::engine::MemChangedEvent)).
//!
//! Mirrors the browser-sync JSON shapes one-to-one: the commit
//! envelope and the SSE event.
//!
//! Two producers exist today:
//! - Native embedders — walk a git-branch tree-diff to build envelopes
//!   from native repos for thin-client consumers.
//! - WASM clients — receive envelopes over the bridge wire and pass
//!   them to [`crate::Engine::apply_external_commit`] to materialize
//!   the new state in their in-memory store.
//!
//! Field order matches the spec; field names are the canonical wire
//! identifiers — do not rename or reshape without bumping the
//! wire-format version.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

/// One commit's wire envelope. JSON example from the spec:
///
/// ```json
/// {
///   "sha": "c4f2a8...",
///   "parent": "a3f9b1...",
///   "mem": "engine",
///   "timestamp": "2026-05-18T14:23:01Z",
///   "trailers": { "Tool": "memstead_update", "Actor": "agent" },
///   "changes": [
///     { "op": "modified", "path": "engine--mem.md", "content": "..." }
///   ]
/// }
/// ```
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CommitEnvelope {
    /// Full commit SHA.
    pub sha: String,
    /// Parent commit SHA. Empty string for the first commit of a
    /// branch (no parent).
    #[serde(skip_serializing_if = "String::is_empty", default)]
    pub parent: String,
    /// Mem name this commit landed on.
    pub mem: String,
    /// Commit timestamp in RFC 3339 / ISO 8601 form (UTC, second
    /// granularity).
    pub timestamp: String,
    /// Commit-message trailers parsed via the engine's standard
    /// trailer convention. Keyed by trailer name (e.g. `Tool`,
    /// `Actor`, `Client`, `Replays`, `Integration-Run`).
    #[serde(skip_serializing_if = "BTreeMap::is_empty", default)]
    pub trailers: BTreeMap<String, String>,
    /// Per-entity changes this commit introduced.
    pub changes: Vec<EntityChange>,
}

/// One entity-level change carried by a [`CommitEnvelope`]. Tagged
/// via the `op` discriminator so the wire shape matches the spec's
/// `{ "op": "...", ... }` envelope.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "op", rename_all = "lowercase")]
pub enum EntityChange {
    /// Entity newly created in this commit.
    Added {
        /// Mem-relative path on the new side (`.md` suffix
        /// included).
        path: String,
        /// Full markdown body on the new side.
        content: String,
    },
    /// Entity body changed in this commit.
    Modified { path: String, content: String },
    /// Entity removed in this commit. No content travels.
    Deleted { path: String },
    /// Entity renamed in this commit. `from` is the pre-rename
    /// path, `to` is the post-rename path; `content` is the body
    /// on the new side.
    Renamed {
        from: String,
        to: String,
        content: String,
    },
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn commit_envelope_json_matches_spec_example() {
        let env = CommitEnvelope {
            sha: "c4f2a8".to_string(),
            parent: "a3f9b1".to_string(),
            mem: "engine".to_string(),
            timestamp: "2026-05-18T14:23:01Z".to_string(),
            trailers: {
                let mut m = BTreeMap::new();
                m.insert("Tool".to_string(), "memstead_update".to_string());
                m.insert("Actor".to_string(), "agent".to_string());
                m
            },
            changes: vec![
                EntityChange::Modified {
                    path: "engine--mem.md".to_string(),
                    content: "body".to_string(),
                },
                EntityChange::Deleted {
                    path: "engine--alt.md".to_string(),
                },
            ],
        };
        let json = serde_json::to_value(&env).unwrap();
        assert_eq!(json["sha"], "c4f2a8");
        assert_eq!(json["parent"], "a3f9b1");
        assert_eq!(json["mem"], "engine");
        assert_eq!(json["timestamp"], "2026-05-18T14:23:01Z");
        assert_eq!(json["trailers"]["Tool"], "memstead_update");
        assert_eq!(json["changes"][0]["op"], "modified");
        assert_eq!(json["changes"][0]["path"], "engine--mem.md");
        assert_eq!(json["changes"][1]["op"], "deleted");
    }

    #[test]
    fn entity_change_renamed_serialises_with_from_to() {
        let c = EntityChange::Renamed {
            from: "engine--x.md".to_string(),
            to: "engine--z.md".to_string(),
            content: "body".to_string(),
        };
        let json = serde_json::to_value(&c).unwrap();
        assert_eq!(json["op"], "renamed");
        assert_eq!(json["from"], "engine--x.md");
        assert_eq!(json["to"], "engine--z.md");
        assert_eq!(json["content"], "body");
    }
}