gemot 0.1.1

Community domain and assembly layer for Moot lifecycle, governance, replication, and Tessera.
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
//! The tessera operation store, over the muniment substrate.
//!
//! [`TesseraStore`] persists a moot's tessera operations through
//! [`stickleback::MunimentStore`], the shared p2panda-store adapter murm and mesh
//! also ride: one operation store that doubles as the `LogStore` + `TopicStore`
//! LogSync reconciles, keyed and folded the same way across all three. One store
//! of record, one write path ([`insert`](TesseraStore::insert)), serving both the
//! projection ([`fold_moot`](TesseraStore::fold_moot)) and sync.
//!
//! Backed by muniment: an in-memory floor for tests, redb on a device (the
//! [`TesseraFileStore`] alias). When the browser backends land (OPFS + IndexedDB),
//! a moot's reputation log rides them with no change here.
//!
//! ## Projection
//!
//! A moot's reputation is the fold of *every* member's tessera log, not one
//! author's. [`fold_moot`](TesseraStore::fold_moot) resolves the moot's
//! `(author, log)` pairs, reads each log's operations, decodes them to
//! [`TesseraEvent`]s, orders them deterministically (by asserted time, then
//! author, then log position — so every peer folds the same events the same way),
//! and runs the [`Ledger`]. The clock stays the caller's: it returns a `Ledger`,
//! and the host asks it for `scores(now_ms)`.

use std::collections::BTreeMap;
use std::path::Path;

use muniment::{Backend, MemoryBackend, RedbBackend, StoreError};
use p2panda_core::{Hash, Operation, Topic, VerifyingKey};
use p2panda_store::logs::LogStore;
use p2panda_store::topics::TopicStore;
use stickleback::{
    Admission, MunimentStore, OperationPolicy, OperationProcessor, ProcessError, Reject,
    StoreTarget,
};

use crate::moot::tessera::event::TesseraEvent;
use crate::moot::tessera::ledger::{Ledger, TesseraConfig};
use crate::moot::tessera::wire::{TesseraExt, from_operation, to_operation_seed};

/// The single per-moot tessera log id: each author keeps one tessera log per moot,
/// so the log id is a constant and the moot id is the topic.
const LOG_ID: u64 = 0;

/// A tessera store failure.
#[derive(Debug, thiserror::Error)]
pub enum TesseraStoreError {
    /// The muniment backend or the store adapter failed.
    #[error(transparent)]
    Store(#[from] StoreError),
    /// The shared policy-before-insert processor rejected or could not store
    /// the operation.
    #[error(transparent)]
    Process(#[from] ProcessError),
    /// A stored operation did not decode to a valid tessera event.
    #[error("malformed tessera operation")]
    Malformed,
}

/// Tessera's current wire-level admission policy.
///
/// It binds every operation to the expected Moot, requires a decodable
/// [`TesseraEvent`], and selects the one per-author Tessera log. The shared
/// processor performs signature, payload, continuity, idempotence, and atomic
/// indexed-write checks before this policy runs. Moot membership, constitution,
/// and moderation authorization deliberately remain a later Moot-domain policy
/// rather than being inferred from reputation events.
#[derive(Clone, Copy)]
struct TesseraPolicy {
    moot_id: [u8; 32],
}

impl OperationPolicy<TesseraExt> for TesseraPolicy {
    type LogId = u64;

    fn admit(&self, operation: &Operation<TesseraExt>) -> Result<Admission<Self::LogId>, Reject> {
        if operation.header.extensions.moot_id != self.moot_id {
            return Err(Reject::new(
                "wrong-moot",
                "operation addresses a different moot",
            ));
        }
        from_operation(operation).map_err(|_| {
            Reject::new(
                "invalid-tessera-event",
                "operation body is not a Tessera event",
            )
        })?;
        Ok(Admission::keep(StoreTarget::new(
            Topic::from(self.moot_id),
            LOG_ID,
        )))
    }
}

/// A tessera operation store over a muniment backend `B`.
///
/// `Clone` shares the same backend handle, so a clone handed to `LogSync::builder`
/// reads and writes the same store.
#[derive(Clone)]
pub struct TesseraStore<B> {
    store: MunimentStore<B, TesseraExt>,
}

/// The durable, redb-backed tessera store — one moot's reputation log on disk.
pub type TesseraFileStore = TesseraStore<RedbBackend>;

impl TesseraStore<MemoryBackend> {
    /// An in-memory tessera store (tests, rehearsals). Nothing persisted.
    pub fn in_memory() -> Self {
        Self {
            store: MunimentStore::new(MemoryBackend::new()),
        }
    }
}

impl TesseraStore<RedbBackend> {
    /// Open or create a redb-backed tessera store at `path`.
    pub fn open(path: impl AsRef<Path>) -> Result<Self, TesseraStoreError> {
        Ok(Self {
            store: MunimentStore::new(RedbBackend::open(path)?),
        })
    }
}

impl<B: Backend + Clone> TesseraStore<B> {
    /// Sign and store the next event in this author's per-Moot Tessera log.
    /// The returned operation is the explicit host-publication seam.
    pub async fn author_seed(
        &self,
        signing_seed: [u8; 32],
        moot_id: [u8; 32],
        event: &TesseraEvent,
    ) -> Result<Operation<TesseraExt>, TesseraStoreError> {
        let author = p2panda_core::SigningKey::from_bytes(&signing_seed).verifying_key();
        let previous = self.store.get_latest_entry(&author, &LOG_ID).await?;
        let (seq_num, backlink) = match previous {
            Some(operation) => (
                operation.header.seq_num + 1,
                Some(*operation.hash.as_bytes()),
            ),
            None => (0, None),
        };
        let operation = to_operation_seed(signing_seed, moot_id, event, seq_num, backlink);
        self.accept(moot_id, &operation).await?;
        Ok(operation)
    }

    /// A clone of the underlying store, for `LogSync::builder` (which takes the
    /// store by value and reconciles through its trait surface).
    pub fn sync_store(&self) -> MunimentStore<B, TesseraExt> {
        self.store.clone()
    }
}

impl<B: Backend + Clone> TesseraStore<B> {
    /// Validate and store a tessera operation under its signed Moot address.
    ///
    /// Prefer [`accept`](Self::accept) at a session boundary, where an expected
    /// Moot prevents cross-space replay before mutation. This convenience keeps
    /// direct authoring on the same processor path by taking the Moot from the
    /// signed extension.
    pub async fn insert(&self, op: &Operation<TesseraExt>) -> Result<bool, TesseraStoreError> {
        self.accept(op.header.extensions.moot_id, op).await
    }

    /// Run the shared policy-before-insert path for `moot_id`.
    ///
    /// Returns `true` for a newly admitted operation and `false` for an accepted
    /// duplicate. A wrong-Moot, malformed, invalid, or discontinuous operation
    /// is rejected before the shared store changes.
    pub async fn accept(
        &self,
        moot_id: [u8; 32],
        op: &Operation<TesseraExt>,
    ) -> Result<bool, TesseraStoreError> {
        let processor = OperationProcessor::new(self.store.clone(), TesseraPolicy { moot_id });
        Ok(processor.process(op).await?.inserted())
    }

    /// Look up an operation by hash.
    pub async fn get(
        &self,
        hash: &Hash,
    ) -> Result<Option<Operation<TesseraExt>>, TesseraStoreError> {
        Ok(self.store.get_operation(hash).await?)
    }

    /// Whether the store holds an operation with this hash.
    pub async fn has(&self, hash: &Hash) -> Result<bool, TesseraStoreError> {
        Ok(self.store.has_operation(hash).await?)
    }

    /// Total operation count.
    pub async fn len(&self) -> Result<usize, TesseraStoreError> {
        Ok(self.store.operation_count().await?)
    }

    /// Whether the store holds no operations.
    pub async fn is_empty(&self) -> Result<bool, TesseraStoreError> {
        Ok(self.store.is_empty().await?)
    }

    /// Fold every member's tessera log in `moot_id` into the moot's [`Ledger`].
    ///
    /// Reputation is the projection over the whole moot, not one author: this
    /// resolves the moot's `(author, log)` pairs, reads each log, decodes the
    /// operations to events, orders them deterministically (asserted time, then
    /// author, then log position — so every peer folds identically), and runs the
    /// ledger. Ask the returned ledger for `scores(now_ms)`.
    pub async fn fold_moot(
        &self,
        moot_id: [u8; 32],
        config: TesseraConfig,
    ) -> Result<Ledger, TesseraStoreError> {
        let logs: BTreeMap<VerifyingKey, Vec<u64>> =
            self.store.resolve(&Topic::from(moot_id)).await?;

        // Collect (asserted time, author, log position, event) across every log.
        let mut tagged: Vec<(u64, [u8; 32], u64, TesseraEvent)> = Vec::new();
        for (author, log_ids) in logs {
            let author_bytes = *author.as_bytes();
            for log_id in log_ids {
                let Some(entries) = self
                    .store
                    .get_log_entries(&author, &log_id, None, None)
                    .await?
                else {
                    continue;
                };
                for (op, _header) in entries {
                    let seq = op.header.seq_num;
                    let (_moot, event) =
                        from_operation(&op).map_err(|_| TesseraStoreError::Malformed)?;
                    tagged.push((event.at_ms(), author_bytes, u64::from(seq), event));
                }
            }
        }

        // Deterministic order, then fold.
        tagged.sort_by_key(|entry| (entry.0, entry.1, entry.2));
        let mut ledger = Ledger::new(config);
        for (_, _, _, event) in &tagged {
            ledger.apply(event);
        }
        Ok(ledger)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::moot::tessera::event::{ChainRoot, CommitmentId, Scope};
    use crate::moot::tessera::wire::to_operation;
    use identity::{Ed25519Keypair, IdentityProvider, InMemoryProvider};
    use tempfile::tempdir;

    const MOOT: [u8; 32] = [0x30; 32];

    fn keypair(seed: u8) -> Ed25519Keypair {
        InMemoryProvider::from_seed([seed; 32])
            .derive_keypair(b"tessera-store-test")
            .unwrap()
    }

    fn root_of(kp: &Ed25519Keypair) -> ChainRoot {
        ChainRoot(kp.public_key().to_bytes())
    }

    /// Author a `commit -> fulfil -> govern` log for `kp`, returning the three
    /// signed operations (a chained per-author log).
    fn commit_fulfil_govern(kp: &Ed25519Keypair) -> [Operation<TesseraExt>; 3] {
        let by = root_of(kp);
        let cid = CommitmentId([0xc1; 32]);
        let e0 = TesseraEvent::CommitmentMade {
            by,
            commitment: cid,
            scope: Scope("host/cluster".into()),
            cadence_ms: 1_000,
            duration_ms: None,
            at_ms: 1_000,
        };
        let e1 = TesseraEvent::CommitmentFulfilled {
            by,
            commitment: cid,
            at_ms: 1_050,
        };
        let e2 = TesseraEvent::GovernanceParticipation { by, at_ms: 1_100 };
        let op0 = to_operation(kp, MOOT, &e0, 0, None);
        let op1 = to_operation(kp, MOOT, &e1, 1, Some(*op0.hash.as_bytes()));
        let op2 = to_operation(kp, MOOT, &e2, 2, Some(*op1.hash.as_bytes()));
        [op0, op1, op2]
    }

    #[tokio::test]
    async fn insert_then_get_round_trips_and_is_idempotent() {
        let store = TesseraStore::in_memory();
        let [op0, op1, op2] = commit_fulfil_govern(&keypair(1));
        assert!(store.insert(&op0).await.unwrap());
        assert!(store.insert(&op1).await.unwrap());
        assert!(store.insert(&op2).await.unwrap());
        assert!(
            !store.insert(&op2).await.unwrap(),
            "re-insert is idempotent on the hash"
        );
        assert_eq!(store.len().await.unwrap(), 3);

        let got = store.get(&op1.hash).await.unwrap().expect("op stored");
        assert_eq!(got.hash, op1.hash);
        assert!(store.has(&op0.hash).await.unwrap());
    }

    #[tokio::test]
    async fn expected_moot_rejects_cross_space_replay_before_mutation() {
        let store = TesseraStore::in_memory();
        let kp = keypair(1);
        let foreign = to_operation(
            &kp,
            [0xee; 32],
            &TesseraEvent::GovernanceParticipation {
                by: root_of(&kp),
                at_ms: 1_000,
            },
            0,
            None,
        );

        assert!(matches!(
            store.accept(MOOT, &foreign).await,
            Err(TesseraStoreError::Process(ProcessError::Rejected(Reject {
                code: "wrong-moot",
                ..
            })))
        ));
        assert!(store.is_empty().await.unwrap());
    }

    #[tokio::test]
    async fn fold_moot_projects_a_single_authors_score() {
        let store = TesseraStore::in_memory();
        let kp = keypair(1);
        for op in commit_fulfil_govern(&kp) {
            store.insert(&op).await.unwrap();
        }
        let ledger = store
            .fold_moot(MOOT, TesseraConfig::default())
            .await
            .unwrap();
        // +10 fulfil, +1 govern = 11; the commitment is closed, so no lapse.
        assert_eq!(ledger.score(&root_of(&kp), 5_000), 11);
    }

    #[tokio::test]
    async fn fold_moot_merges_every_members_log() {
        let store = TesseraStore::in_memory();
        let alice = keypair(1);
        let bob = keypair(2);
        // Alice: commit -> fulfil -> govern = 11. Bob: one governance = 1.
        for op in commit_fulfil_govern(&alice) {
            store.insert(&op).await.unwrap();
        }
        let bob_govern = TesseraEvent::GovernanceParticipation {
            by: root_of(&bob),
            at_ms: 1_200,
        };
        store
            .insert(&to_operation(&bob, MOOT, &bob_govern, 0, None))
            .await
            .unwrap();

        let ledger = store
            .fold_moot(MOOT, TesseraConfig::default())
            .await
            .unwrap();
        assert_eq!(ledger.score(&root_of(&alice), 5_000), 11);
        assert_eq!(ledger.score(&root_of(&bob), 5_000), 1);
    }

    #[tokio::test]
    async fn fold_moot_ignores_a_foreign_moot() {
        let store = TesseraStore::in_memory();
        let kp = keypair(1);
        for op in commit_fulfil_govern(&kp) {
            store.insert(&op).await.unwrap();
        }
        // A different moot id resolves to no logs, so the fold is empty.
        let ledger = store
            .fold_moot([0xee; 32], TesseraConfig::default())
            .await
            .unwrap();
        assert_eq!(ledger.score(&root_of(&kp), 5_000), 0);
    }

    #[tokio::test]
    async fn operations_persist_across_reopen() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("moot.redb");
        let kp = keypair(1);
        let ops = commit_fulfil_govern(&kp);
        {
            let store = TesseraStore::open(&path).unwrap();
            for op in &ops {
                store.insert(op).await.unwrap();
            }
            assert_eq!(store.len().await.unwrap(), 3);
        }
        // Reopen: the log and its projection survive.
        let store = TesseraStore::open(&path).unwrap();
        assert_eq!(store.len().await.unwrap(), 3);
        let ledger = store
            .fold_moot(MOOT, TesseraConfig::default())
            .await
            .unwrap();
        assert_eq!(ledger.score(&root_of(&kp), 5_000), 11);
    }
}