Skip to main content

mnemo_engine/store/
coordination.rs

1//! 13a (v0.17): coordination records, `message`, `task`, `claim` and
2//! `presence` (`docs/design/13a-coordination.md`). Step 1 is the plumbing:
3//! the kinds are stored as ordinary records in the shared scope with the
4//! sentinel vector, and kept out of recall, the keyword index, the ANN and
5//! `about` (see `is_coordination`). Each kind's API comes in its own step.
6
7use super::*;
8
9impl Mnemo {
10    /// Write a coordination record of `kind` (one of
11    /// [`crate::memory::COORDINATION_KINDS`]) holding `content` and
12    /// `metadata` (whose `_mnemo.*` keys the caller of this internal path
13    /// sets): shared scope, the sentinel vector, never embedded. The
14    /// handle's author is stamped like any new record's.
15    // The test hook's; the APIs use `put_coordination_with_id`.
16    #[cfg_attr(not(feature = "dev-hooks"), allow(dead_code))]
17    pub(super) fn put_coordination(
18        &mut self,
19        kind: &str,
20        content: String,
21        metadata: Map<String, Value>,
22    ) -> Result<Ulid> {
23        self.put_coordination_with_id(Ulid::new(), kind, content, metadata)
24    }
25
26    /// [`Mnemo::put_coordination`] with the record's id chosen first (a
27    /// message's id names its conversation).
28    pub(super) fn put_coordination_with_id(
29        &mut self,
30        id: Ulid,
31        kind: &str,
32        content: String,
33        mut metadata: Map<String, Value>,
34    ) -> Result<Ulid> {
35        if self.read_only {
36            return Err(MnemoError::ReadOnly);
37        }
38        if !crate::memory::COORDINATION_KINDS.contains(&kind) {
39            return Err(MnemoError::Invalid(format!(
40                "{kind:?} isn't a coordination kind"
41            )));
42        }
43        metadata.insert(MNEMO_META_KIND.into(), Value::String(kind.to_string()));
44        let mut m = Memory::new(content, MemoryType::Episodic, self.sentinel_vector())
45            .with_scope(Scope::Shared);
46        m.id = id;
47        m.metadata = metadata;
48        self.put(m)
49    }
50}
51
52/// 13a (13.1): one message between agents, as [`Mnemo::inbox`] returns it.
53#[derive(Debug, Clone, Default, PartialEq)]
54#[non_exhaustive]
55pub struct Message {
56    /// The record's id.
57    pub id: Ulid,
58    /// An agent id, `role:<role>`, or `all`.
59    pub to: String,
60    /// The sender as it said, unproven until 13b.
61    pub from: String,
62    /// One line.
63    pub subject: String,
64    /// The body (may be empty).
65    pub body: String,
66    /// Record ids, a PR number, a ledger entry title.
67    pub refs: Vec<String>,
68    /// The conversation it belongs to.
69    pub conversation: String,
70    /// Its hop count (13.1b's hop cap).
71    pub hops: u64,
72    /// `unread` or `acked`.
73    pub status: String,
74    /// `sent`, `delivered`, `seen` or `done`.
75    pub delivery: String,
76    /// When it was posted, in unix seconds.
77    pub created_at: i64,
78    /// When it was acked, if it was.
79    pub acked_at: Option<i64>,
80}
81
82impl Message {
83    /// The message a record holds, if it's one.
84    pub fn from_memory(m: &Memory) -> Option<Message> {
85        if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)
86            != Some(crate::memory::MNEMO_META_KIND_MESSAGE)
87        {
88            return None;
89        }
90        let s = |k: &str| {
91            m.metadata
92                .get(k)
93                .and_then(Value::as_str)
94                .unwrap_or("")
95                .to_string()
96        };
97        let (subject, body) = match m.content.split_once("\n\n") {
98            Some((a, b)) => (a.to_string(), b.to_string()),
99            None => (m.content.clone(), String::new()),
100        };
101        Some(Message {
102            id: m.id,
103            to: s(MNEMO_META_TO),
104            from: s(MNEMO_META_FROM),
105            subject,
106            body,
107            refs: m
108                .metadata
109                .get(MNEMO_META_REFS)
110                .and_then(Value::as_array)
111                .map(|a| {
112                    a.iter()
113                        .filter_map(|v| v.as_str().map(str::to_string))
114                        .collect()
115                })
116                .unwrap_or_default(),
117            conversation: s(MNEMO_META_CONVERSATION),
118            hops: m
119                .metadata
120                .get(MNEMO_META_HOPS)
121                .and_then(Value::as_u64)
122                .unwrap_or(0),
123            status: s(MNEMO_META_STATUS),
124            delivery: s(MNEMO_META_DELIVERY),
125            created_at: m.created_at,
126            acked_at: m.metadata.get(MNEMO_META_ACKED_AT).and_then(Value::as_i64),
127        })
128    }
129
130    /// Whether it's addressed to `agent` (by id), to `role`, or to everyone,
131    /// and isn't from `agent` itself.
132    pub fn is_for(&self, agent: Option<&str>, role: Option<&str>) -> bool {
133        if agent.is_some_and(|a| a == self.from) {
134            return false;
135        }
136        self.to == "all"
137            || agent.is_some_and(|a| a == self.to)
138            || role.is_some_and(|r| self.to.strip_prefix("role:") == Some(r))
139    }
140}
141
142/// Whether `to` is an address: an agent id, `role:<role>`, or `all`.
143fn valid_address(to: &str) -> bool {
144    to == "all"
145        || crate::memory::valid_agent_id(to) && !to.starts_with("role:")
146        || to
147            .strip_prefix("role:")
148            .is_some_and(crate::memory::valid_agent_id)
149}
150
151/// 13a (RB-012.6 item 4): the agents a broadcast message or a role's task
152/// has been shown to (`_mnemo.seen_by`).
153fn seen_by(m: &Memory) -> Vec<String> {
154    m.metadata
155        .get(crate::memory::MNEMO_META_SEEN_BY)
156        .and_then(Value::as_array)
157        .map(|a| {
158            a.iter()
159                .filter_map(|v| v.as_str().map(str::to_string))
160                .collect()
161        })
162        .unwrap_or_default()
163}
164
165/// COORD-LEGACY-SCAN: whether a stored (fp16) vector is the sentinel every
166/// coordination record carries: all its values equal, at 1/sqrt(dims).
167fn is_sentinel(h: &[u16]) -> bool {
168    let Some(&first) = h.first() else {
169        return false;
170    };
171    let want = 1.0 / (h.len() as f32).sqrt();
172    h.iter().all(|&x| x == first) && (crate::veccol::f16_to_f32(first) - want).abs() < 1e-3
173}
174
175/// READY-NOTICE: the agents a `ready` task was shown to as theirs to
176/// close (`_mnemo.ready_seen_by`).
177fn ready_seen_by(m: &Memory) -> Vec<String> {
178    m.metadata
179        .get(crate::memory::MNEMO_META_READY_SEEN_BY)
180        .and_then(Value::as_array)
181        .map(|a| {
182            a.iter()
183                .filter_map(|v| v.as_str().map(str::to_string))
184                .collect()
185        })
186        .unwrap_or_default()
187}
188
189/// Add `agent` to a record's `_mnemo.seen_by`; `false` when it was there.
190fn add_seen_by(m: &mut Memory, agent: &str) -> bool {
191    let mut v = seen_by(m);
192    if v.iter().any(|a| a == agent) {
193        return false;
194    }
195    v.push(agent.to_string());
196    m.metadata.insert(
197        crate::memory::MNEMO_META_SEEN_BY.into(),
198        Value::Array(v.into_iter().map(Value::String).collect()),
199    );
200    true
201}
202
203impl Mnemo {
204    /// Every live coordination record of `kind`, in catalog order; with a
205    /// `locator` (a claim's topic, a presence record's agent), only that
206    /// one's, found through its row's hash without decrypting the rest.
207    pub(super) fn coordination_records(
208        &mut self,
209        kind: &str,
210        locator: Option<&str>,
211    ) -> Result<Vec<Memory>> {
212        let want = locator.map(|l| locator_hash_of(kind, l));
213        let legacy = self.legacy_coordination_ids()?;
214        let entries: Vec<CatalogEntry> = self
215            .catalog
216            .iter()
217            .filter(|e| !e.deleted)
218            .filter(|e| {
219                legacy.contains(&e.id)
220                    || e.v9.is_none_or(|r| {
221                        r.kind == ROW_KIND_COORDINATION && want.is_none_or(|h| r.thread_hash == h)
222                    })
223            })
224            .cloned()
225            .collect();
226        let mut out = Vec::new();
227        for e in entries {
228            let m = self.read_memory(&e)?;
229            if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(kind) {
230                continue;
231            }
232            if let Some(l) = locator {
233                if locator_of(&m) != Some(l) {
234                    continue;
235                }
236            }
237            out.push(m);
238        }
239        Ok(out)
240    }
241
242    /// RB-013.1: the coordination records an older build re-tagged as facts
243    /// (its `compact` writes every row again, and it computes "fact" for a
244    /// kind it doesn't know). Found once per handle: such a record keeps
245    /// its `episodic` type in the row and its sentinel vector in the column,
246    /// so only `episodic` fact rows whose vector is the sentinel are
247    /// decrypted (COORD-LEGACY-SCAN, v0.17.2); a row whose vector can't be
248    /// read is decrypted, as before. A write of one re-tags its row.
249    fn legacy_coordination_ids(&mut self) -> Result<std::collections::HashSet<u128>> {
250        if let Some(ids) = &self.legacy_coordination {
251            return Ok(ids.clone());
252        }
253        let episodic = super::records::memory_type_code(MemoryType::Episodic);
254        let candidates: Vec<CatalogEntry> = self
255            .catalog
256            .iter()
257            .filter(|e| !e.deleted)
258            .filter(|e| {
259                e.v9.is_some_and(|r| {
260                    r.kind == super::records::ROW_KIND_FACT && r.memory_type == episodic
261                })
262            })
263            .cloned()
264            .collect();
265        let mut ids = std::collections::HashSet::new();
266        // Each vector page read once, for every candidate row on it.
267        let mut pages: std::collections::HashMap<(u64, u64), Option<Vec<u8>>> =
268            std::collections::HashMap::new();
269        for e in candidates {
270            let vector = match e.v9 {
271                Some(r) if r.vec_page != 0 && !self.has_hot_vector(&e) => {
272                    let page = pages
273                        .entry((r.vec_page, r.vec_gen))
274                        .or_insert_with(|| self.pager.read_page(r.vec_page, r.vec_gen).ok());
275                    page.as_ref().and_then(|p| {
276                        crate::veccol::decode_entry(p, self.dimensions, r.vec_slot as usize).ok()
277                    })
278                }
279                _ => self.column_entry(&e).ok(),
280            };
281            if matches!(vector, Some((h, _)) if !is_sentinel(&h)) {
282                continue;
283            }
284            if is_coordination(&self.read_memory(&e)?) {
285                ids.insert(e.id);
286            }
287        }
288        self.legacy_coordination = Some(ids.clone());
289        Ok(ids)
290    }
291
292    /// RB-013.1: how many coordination records are tagged as facts in their
293    /// rows (an older mnemo rewrote this brain); `mnemo compact` re-tags
294    /// them. They're found and used all the same.
295    pub fn mistagged_coordination(&mut self) -> Result<usize> {
296        let ids = self.legacy_coordination_ids()?;
297        Ok(self
298            .catalog
299            .iter()
300            .filter(|e| !e.deleted && ids.contains(&e.id))
301            .filter(|e| {
302                e.v9.is_some_and(|r| r.kind == super::records::ROW_KIND_FACT)
303            })
304            .count())
305    }
306
307    /// Every live message, oldest first.
308    fn messages(&mut self) -> Result<Vec<Memory>> {
309        let mut out = self.coordination_records(crate::memory::MNEMO_META_KIND_MESSAGE, None)?;
310        // Stable: within one second (`created_at`'s grain) the catalog's
311        // order, which is the order they were written.
312        out.sort_by_key(|m| m.created_at);
313        Ok(out)
314    }
315
316    /// 13a (13.1): post a message to `to` (an agent id, `role:<role>`, or
317    /// `all`) with a one-line `subject` and an optional `body` (at most
318    /// [`crate::memory::MESSAGE_BODY_MAX`] bytes), from `from` (else the
319    /// handle's author, else `anonymous`), in `from_role` when given.
320    ///
321    /// A reply names its `conversation`, and its hop count is one more than
322    /// the conversation's highest. A new message between the same two
323    /// parties within [`crate::memory::MESSAGE_PAIR_CARRY_SECS`] starts one
324    /// above the highest count between them in that time, so agents trading
325    /// fresh messages still reach the hop cap. Its delivery is `sent` and its status `unread`.
326    // Each is a message's own field; a request struct would only rename them.
327    #[allow(clippy::too_many_arguments)]
328    pub fn post(
329        &mut self,
330        to: &str,
331        subject: &str,
332        body: &str,
333        refs: &[String],
334        conversation: Option<&str>,
335        from: Option<&str>,
336        from_role: Option<&str>,
337    ) -> Result<Message> {
338        if self.read_only {
339            return Err(MnemoError::ReadOnly);
340        }
341        if !valid_address(to) {
342            return Err(MnemoError::Invalid(format!(
343                "{to:?} isn't an address: an agent id, role:<role>, or all"
344            )));
345        }
346        let subject = subject.trim();
347        if subject.is_empty() || subject.contains('\n') {
348            return Err(MnemoError::Invalid(
349                "a message's subject is one line, and not empty".into(),
350            ));
351        }
352        if subject.len() > crate::memory::MESSAGE_SUBJECT_MAX {
353            return Err(MnemoError::Invalid(format!(
354                "a message's subject is at most {} bytes",
355                crate::memory::MESSAGE_SUBJECT_MAX
356            )));
357        }
358        if body.len() > crate::memory::MESSAGE_BODY_MAX {
359            return Err(MnemoError::Invalid(format!(
360                "a message's body is at most {} bytes; put a longer one in a fact and send its id \
361                 in refs",
362                crate::memory::MESSAGE_BODY_MAX
363            )));
364        }
365        let from = from
366            .map(str::to_string)
367            .or_else(|| self.author.clone())
368            .unwrap_or_else(|| "anonymous".to_string());
369        let now = memory::now_secs();
370        let earlier: Vec<Message> = self
371            .messages()?
372            .iter()
373            .filter_map(Message::from_memory)
374            .collect();
375        let mut hops = 0u64;
376        if let Some(c) = conversation {
377            if let Some(h) = earlier
378                .iter()
379                .filter(|m| m.conversation == c)
380                .map(|m| m.hops)
381                .max()
382            {
383                hops = h + 1;
384            }
385        }
386        // The pair carry: one more than the highest count between these two,
387        // either way, in the window.
388        if let Some(h) = earlier
389            .iter()
390            .filter(|m| now - m.created_at <= crate::memory::MESSAGE_PAIR_CARRY_SECS)
391            .filter(|m| (m.from == from && m.to == to) || (m.from == to && m.to == from))
392            .map(|m| m.hops)
393            .max()
394        {
395            hops = hops.max(h + 1);
396        }
397        let id = Ulid::new();
398        let conversation = conversation
399            .map(str::to_string)
400            .unwrap_or_else(|| id.to_string());
401        let mut meta = Map::new();
402        meta.insert(MNEMO_META_TO.into(), Value::String(to.into()));
403        meta.insert(MNEMO_META_FROM.into(), Value::String(from));
404        if let Some(r) = from_role {
405            meta.insert("_mnemo.from_role".into(), Value::String(r.to_string()));
406        }
407        meta.insert(MNEMO_META_CONVERSATION.into(), Value::String(conversation));
408        meta.insert(MNEMO_META_HOPS.into(), Value::from(hops));
409        meta.insert(
410            MNEMO_META_REFS.into(),
411            Value::Array(refs.iter().map(|r| Value::String(r.clone())).collect()),
412        );
413        meta.insert(
414            MNEMO_META_STATUS.into(),
415            Value::String(crate::memory::MESSAGE_UNREAD.into()),
416        );
417        meta.insert(
418            MNEMO_META_DELIVERY.into(),
419            Value::String(crate::memory::delivery::SENT.into()),
420        );
421        let content = if body.is_empty() {
422            subject.to_string()
423        } else {
424            format!("{subject}\n\n{body}")
425        };
426        let id = self.put_coordination_with_id(
427            id,
428            crate::memory::MNEMO_META_KIND_MESSAGE,
429            content,
430            meta,
431        )?;
432        let m = self.get(&id)?;
433        Ok(Message::from_memory(&m).expect("just written"))
434    }
435
436    /// 13a (13.1): the messages for `agent` (by id), its `role`, or
437    /// everyone, oldest first, leaving out its own. With `unread_only`,
438    /// only those not yet acked. Reads only; [`Mnemo::mark_seen`] records
439    /// that they were shown.
440    pub fn inbox(
441        &mut self,
442        agent: Option<&str>,
443        role: Option<&str>,
444        unread_only: bool,
445    ) -> Result<Vec<Message>> {
446        self.inbox_in(
447            agent,
448            role,
449            unread_only,
450            crate::memory::VisibilitySet::DEFAULT,
451        )
452    }
453
454    /// 13a (13.5): [`Mnemo::inbox`] with the visibility levels it shows
455    /// (`inbox` itself shows public and team).
456    pub fn inbox_in(
457        &mut self,
458        agent: Option<&str>,
459        role: Option<&str>,
460        unread_only: bool,
461        visibility: crate::memory::VisibilitySet,
462    ) -> Result<Vec<Message>> {
463        Ok(self
464            .messages()?
465            .iter()
466            .filter(|m| visibility.shows(m))
467            .filter_map(Message::from_memory)
468            .filter(|m| m.is_for(agent, role))
469            .filter(|m| !unread_only || m.status == crate::memory::MESSAGE_UNREAD)
470            .collect())
471    }
472
473    /// 13a (13.1b): mark these messages `seen` (from `sent` or `delivered`),
474    /// in place. Returns how many changed.
475    pub fn mark_seen(&mut self, ids: &[Ulid]) -> Result<usize> {
476        if self.read_only {
477            return Err(MnemoError::ReadOnly);
478        }
479        let mut changed = 0;
480        for id in ids {
481            let mut m = self.get(id)?;
482            let Some(msg) = Message::from_memory(&m) else {
483                continue;
484            };
485            let mut dirty = false;
486            if msg.delivery == crate::memory::delivery::SENT
487                || msg.delivery == crate::memory::delivery::DELIVERED
488            {
489                m.metadata.insert(
490                    MNEMO_META_DELIVERY.into(),
491                    Value::String(crate::memory::delivery::SEEN.into()),
492                );
493                dirty = true;
494            }
495            // RB-012.6 item 4: a message to a role or everyone is seen per
496            // agent (this handle's author).
497            if msg.to == "all" || msg.to.starts_with("role:") {
498                if let Some(a) = self.author.clone() {
499                    dirty |= add_seen_by(&mut m, &a);
500                }
501            }
502            if dirty {
503                self.put(m)?;
504                changed += 1;
505            }
506        }
507        Ok(changed)
508    }
509
510    /// 13a (13.1): ack a message, in place: `unread → acked`, its delivery
511    /// `done`, and a `status_history` entry with `by` (else the handle's
512    /// author) and the optional `note`. `Unchanged` when it's already
513    /// acked; an id that isn't a message is refused.
514    pub fn ack(&mut self, id: &Ulid, note: Option<&str>, by: Option<&str>) -> Result<WriteOutcome> {
515        if self.read_only {
516            return Err(MnemoError::ReadOnly);
517        }
518        let mut m = self.get(id)?;
519        let Some(msg) = Message::from_memory(&m) else {
520            return Err(MnemoError::Invalid(format!("{id} isn't a message")));
521        };
522        if msg.status == crate::memory::MESSAGE_ACKED {
523            return Ok(WriteOutcome::Unchanged);
524        }
525        let now = memory::now_secs();
526        let by = by
527            .map(str::to_string)
528            .or_else(|| self.author.clone())
529            .unwrap_or_else(|| "anonymous".to_string());
530        let mut entry = Map::new();
531        entry.insert("from".into(), Value::String(msg.status.clone()));
532        entry.insert(
533            "to".into(),
534            Value::String(crate::memory::MESSAGE_ACKED.into()),
535        );
536        entry.insert("at".into(), Value::from(now));
537        entry.insert("by".into(), Value::String(by));
538        if let Some(n) = note {
539            entry.insert("note".into(), Value::String(n.to_string()));
540        }
541        let mut history = m
542            .metadata
543            .get(MNEMO_META_STATUS_HISTORY)
544            .and_then(Value::as_array)
545            .cloned()
546            .unwrap_or_default();
547        history.push(Value::Object(entry));
548        m.metadata
549            .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(history));
550        m.metadata.insert(
551            MNEMO_META_STATUS.into(),
552            Value::String(crate::memory::MESSAGE_ACKED.into()),
553        );
554        m.metadata.insert(
555            MNEMO_META_DELIVERY.into(),
556            Value::String(crate::memory::delivery::DONE.into()),
557        );
558        m.metadata
559            .insert(MNEMO_META_ACKED_AT.into(), Value::from(now));
560        self.put(m)?;
561        Ok(WriteOutcome::Updated)
562    }
563
564    /// 13a (R-010.8): delete messages acked more than `older_than_secs` ago
565    /// ([`crate::memory::MESSAGE_ACKED_KEEP_SECS`] by default in the CLI).
566    /// Returns how many went. `compact` drops the same ones.
567    pub fn prune_messages(&mut self, older_than_secs: i64) -> Result<usize> {
568        if self.read_only {
569            return Err(MnemoError::ReadOnly);
570        }
571        let now = memory::now_secs();
572        let old: Vec<Ulid> = self
573            .messages()?
574            .iter()
575            .filter_map(Message::from_memory)
576            .filter(|m| prunable(m, now, older_than_secs))
577            .map(|m| m.id)
578            .collect();
579        for id in &old {
580            self.delete(id)?;
581        }
582        Ok(old.len())
583    }
584}
585
586/// Whether a message is acked and older than `keep` seconds.
587fn prunable(m: &Message, now: i64, keep: i64) -> bool {
588    m.status == crate::memory::MESSAGE_ACKED && m.acked_at.is_some_and(|t| now - t > keep)
589}
590
591/// 13a (R-010.8): whether `compact` leaves this record out: a message acked
592/// more than [`crate::memory::MESSAGE_ACKED_KEEP_SECS`] ago.
593pub(super) fn compact_drops(m: &Memory, now: i64) -> bool {
594    Message::from_memory(m)
595        .is_some_and(|msg| prunable(&msg, now, crate::memory::MESSAGE_ACKED_KEEP_SECS))
596}
597
598// --- 13a step 3: claims and presence (13.3) ---------------------------------
599
600use crate::memory::{
601    CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
602    MNEMO_META_AGENT, MNEMO_META_CLAIM_TOKEN, MNEMO_META_DEAD_SEEN_AT, MNEMO_META_EXPIRES_AT,
603    MNEMO_META_HOLDER, MNEMO_META_HOLDER_LOCK, MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_PRESENCE,
604    MNEMO_META_LAST_ACTIVE, MNEMO_META_LEASE, MNEMO_META_PRESENCE_LOCK, MNEMO_META_TOOL,
605    MNEMO_META_TOPIC, PRESENCE_EVERY_SECS,
606};
607
608/// A claim's or presence record's locator: its topic or its agent.
609fn locator_of(m: &Memory) -> Option<&str> {
610    let key = match m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)? {
611        MNEMO_META_KIND_CLAIM => MNEMO_META_TOPIC,
612        MNEMO_META_KIND_PRESENCE => MNEMO_META_AGENT,
613        crate::memory::MNEMO_META_KIND_TASK => crate::memory::MNEMO_META_SLUG,
614        crate::memory::MNEMO_META_KIND_FINDING => crate::memory::MNEMO_META_FINDING_ID,
615        _ => return None,
616    };
617    m.metadata.get(key).and_then(Value::as_str)
618}
619
620fn locator_hash_of(kind: &str, locator: &str) -> u32 {
621    super::records::fnv1a32(&[b"_mnemo.coordination", kind.as_bytes(), locator.as_bytes()])
622}
623
624/// The hash a coordination record's v9 row carries in place of a thread
625/// hash: of its kind and topic (a claim) or agent (presence); `0` for the
626/// other kinds.
627pub(super) fn locator_hash(m: &Memory) -> u32 {
628    match (
629        m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str),
630        locator_of(m),
631    ) {
632        (Some(kind), Some(l)) => locator_hash_of(kind, l),
633        _ => 0,
634    }
635}
636
637/// 13a (13.3): what [`Mnemo::claim`] got.
638#[derive(Debug, Clone, PartialEq, Eq)]
639pub enum ClaimOutcome {
640    /// The claim is this agent's. Keep the token: `renew`, `release` and
641    /// `check_claim` need it.
642    Claimed {
643        /// The claim's token.
644        token: String,
645        /// When it lapses unless renewed, in unix seconds.
646        expires_at: i64,
647    },
648    /// Another agent (or this one, in another process or session) holds it.
649    HeldBy {
650        /// The holder.
651        agent: String,
652        /// When it lapses unless renewed.
653        expires_at: i64,
654    },
655}
656
657/// 13a (13.3): what `renew`, `release` and `check_claim` found.
658#[derive(Debug, Clone, Copy, PartialEq, Eq)]
659pub enum ClaimStatus {
660    /// The claim is still the token's, until `expires_at`.
661    Held {
662        /// When it lapses unless renewed, in unix seconds.
663        expires_at: i64,
664    },
665    /// Released.
666    Released,
667    /// The claim lapsed or another agent holds it now: whatever it guarded
668    /// may have been done by someone else. Check before an irreversible
669    /// step.
670    Lost,
671}
672
673/// 13a (13.3): a live claim, as [`Mnemo::claims`] lists it (no token).
674#[derive(Debug, Clone, Default, PartialEq, Eq)]
675#[non_exhaustive]
676pub struct Claim {
677    /// What's claimed.
678    pub topic: String,
679    /// Who holds it.
680    pub holder: String,
681    /// When it lapses unless renewed.
682    pub expires_at: i64,
683    /// Its lease, in seconds.
684    pub lease: i64,
685}
686
687/// 13a (13.3): whether an agent's process is running, by its presence lock.
688#[derive(Debug, Clone, Copy, PartialEq, Eq)]
689pub enum Alive {
690    /// Its long-lived process holds its presence lock.
691    Yes,
692    /// It registered a lock, and the lock is free: its process is gone.
693    No,
694    /// It has no long-lived process (the CLI, a session without the MCP
695    /// server), or the probe couldn't tell.
696    Unknown,
697}
698
699/// 13a (13.3): one agent, as [`Mnemo::who`] lists it.
700#[derive(Debug, Clone, PartialEq, Eq)]
701#[non_exhaustive]
702pub struct Presence {
703    /// The agent id.
704    pub agent: String,
705    /// Its role, if it gave one.
706    pub role: Option<String>,
707    /// The tool it last wrote through (`mcp`, `cli`, ...).
708    pub tool: Option<String>,
709    /// When it last wrote, in unix seconds (updated at most once a minute).
710    pub last_active: i64,
711    /// Whether its process is running.
712    pub alive: Alive,
713    /// The topics it holds live claims on.
714    pub claims: Vec<String>,
715}
716
717fn meta_i64(m: &Memory, k: &str) -> Option<i64> {
718    m.metadata.get(k).and_then(Value::as_i64)
719}
720
721fn meta_string(m: &Memory, k: &str) -> Option<String> {
722    m.metadata
723        .get(k)
724        .and_then(Value::as_str)
725        .map(str::to_string)
726}
727
728/// A claim record's expiry, bounded by one lease from `now`: a clock that
729/// stepped back can't stretch a claim past its lease.
730fn effective_expiry(m: &Memory, now: i64) -> Option<i64> {
731    let token = m
732        .metadata
733        .get(MNEMO_META_CLAIM_TOKEN)
734        .and_then(Value::as_str)?;
735    if token.is_empty() {
736        return None;
737    }
738    let expires = meta_i64(m, MNEMO_META_EXPIRES_AT)?;
739    let lease = meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT);
740    Some(expires.min(now.saturating_add(lease)))
741}
742
743/// Whether a claim record is held at `now`.
744fn is_live(m: &Memory, now: i64) -> bool {
745    effective_expiry(m, now).is_some_and(|e| now < e)
746}
747
748fn new_token() -> String {
749    format!(
750        "{:016x}{:016x}",
751        crate::crypto::random_u64(),
752        crate::crypto::random_u64()
753    )
754}
755
756fn check_topic(topic: &str) -> Result<()> {
757    if topic.trim().is_empty() || topic.contains('\n') || topic.len() > CLAIM_TOPIC_MAX {
758        return Err(MnemoError::Invalid(format!(
759            "a claim's topic is one line, not empty, at most {CLAIM_TOPIC_MAX} bytes"
760        )));
761    }
762    Ok(())
763}
764
765fn check_ttl(ttl: Option<i64>) -> Result<i64> {
766    let t = ttl.unwrap_or(CLAIM_TTL_DEFAULT);
767    if !(CLAIM_TTL_MIN..=CLAIM_TTL_MAX).contains(&t) {
768        return Err(MnemoError::Invalid(format!(
769            "a claim's ttl is {CLAIM_TTL_MIN} s to {CLAIM_TTL_MAX} s (24 h); got {t}"
770        )));
771    }
772    Ok(t)
773}
774
775impl Mnemo {
776    /// 13a: the clock claims, leases and presence run on, in unix seconds:
777    /// the wall clock (dev-hooks builds let tests shift it).
778    pub fn coordination_now(&self) -> i64 {
779        #[cfg(feature = "dev-hooks")]
780        let env: i64 = std::env::var("MNEMO_DEV_CLOCK_OFFSET")
781            .ok()
782            .and_then(|v| v.parse().ok())
783            .unwrap_or(0);
784        #[cfg(not(feature = "dev-hooks"))]
785        let env: i64 = 0;
786        memory::now_secs() + self.clock_offset + env
787    }
788
789    /// **Not a stable API** (dev-hooks builds only): shift this handle's
790    /// coordination clock by `secs`.
791    #[cfg(feature = "dev-hooks")]
792    #[doc(hidden)]
793    pub fn __set_clock_offset_for_testing(&mut self, secs: i64) {
794        self.clock_offset = secs;
795    }
796
797    fn claim_agent(&self) -> Result<String> {
798        self.author.clone().ok_or_else(|| {
799            MnemoError::Invalid(
800                "a claim needs an agent: set MNEMO_AGENT (or --as), or call set_author".into(),
801            )
802        })
803    }
804
805    fn find_claim(&mut self, topic: &str) -> Result<Option<Memory>> {
806        Ok(self
807            .coordination_records(MNEMO_META_KIND_CLAIM, Some(topic))?
808            .into_iter()
809            .next())
810    }
811
812    /// 13a (13.3): claim `topic` for this handle's author for `ttl` seconds
813    /// ([`crate::memory::CLAIM_TTL_DEFAULT`], 15 minutes, by default; 30 s
814    /// to 24 h).
815    ///
816    /// A claim is a record, not a lock, and it's advisory: nothing refuses
817    /// a write because of one. In a shared handle's write window it's a
818    /// compare-and-set: two processes can't both win. The topic is free
819    /// when nobody holds it, its claim lapsed at `expires_at`, or its
820    /// holder registered a presence lock when it claimed and has been seen
821    /// not alive twice, [`crate::memory::CLAIM_LAPSE_GRACE_SECS`] apart
822    /// (each look is recorded on the claim). A topic this agent already
823    /// holds is [`ClaimOutcome::HeldBy`] too: a token can't be recovered.
824    /// One record per topic, changed in place: a new holder gets a new
825    /// token.
826    pub fn claim(&mut self, topic: &str, ttl: Option<i64>) -> Result<ClaimOutcome> {
827        if self.read_only {
828            return Err(MnemoError::ReadOnly);
829        }
830        check_topic(topic)?;
831        let ttl = check_ttl(ttl)?;
832        let agent = self.claim_agent()?;
833        let now = self.coordination_now();
834        let existing = self.find_claim(topic)?;
835        if let Some(mut m) = existing.clone() {
836            if is_live(&m, now) {
837                let holder = meta_string(&m, MNEMO_META_HOLDER).unwrap_or_default();
838                let expires = effective_expiry(&m, now).unwrap_or(now);
839                let mut changed = false;
840                let mut lapse = false;
841                let had_lock = m
842                    .metadata
843                    .get(MNEMO_META_HOLDER_LOCK)
844                    .and_then(Value::as_bool)
845                    .unwrap_or(false);
846                if had_lock && holder != agent {
847                    match crate::shared::probe_presence_once(&self.path, &holder) {
848                        Some(false) => match meta_i64(&m, MNEMO_META_DEAD_SEEN_AT) {
849                            Some(t) if now - t >= CLAIM_LAPSE_GRACE_SECS => lapse = true,
850                            Some(_) => {}
851                            None => {
852                                m.metadata
853                                    .insert(MNEMO_META_DEAD_SEEN_AT.into(), Value::from(now));
854                                changed = true;
855                            }
856                        },
857                        _ => {
858                            changed |= m.metadata.remove(MNEMO_META_DEAD_SEEN_AT).is_some();
859                        }
860                    }
861                }
862                if !lapse {
863                    // A clock that stepped back: bring the stored expiry
864                    // within one lease.
865                    if meta_i64(&m, MNEMO_META_EXPIRES_AT) != Some(expires) {
866                        m.metadata
867                            .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires));
868                        changed = true;
869                    }
870                    if changed {
871                        self.put(m)?;
872                    }
873                    return Ok(ClaimOutcome::HeldBy {
874                        agent: holder,
875                        expires_at: expires,
876                    });
877                }
878            }
879        }
880        let token = new_token();
881        let expires_at = now + ttl;
882        let mut meta = existing
883            .as_ref()
884            .map(|m| m.metadata.clone())
885            .unwrap_or_default();
886        meta.remove(MNEMO_META_DEAD_SEEN_AT);
887        meta.insert(MNEMO_META_TOPIC.into(), Value::String(topic.to_string()));
888        meta.insert(MNEMO_META_HOLDER.into(), Value::String(agent));
889        meta.insert(MNEMO_META_CLAIM_TOKEN.into(), Value::String(token.clone()));
890        meta.insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
891        meta.insert(MNEMO_META_LEASE.into(), Value::from(ttl));
892        meta.insert(
893            MNEMO_META_HOLDER_LOCK.into(),
894            Value::Bool(self.presence_held),
895        );
896        match existing {
897            Some(mut m) => {
898                m.metadata = meta;
899                self.put(m)?;
900            }
901            None => {
902                self.put_coordination_with_id(
903                    Ulid::new(),
904                    MNEMO_META_KIND_CLAIM,
905                    format!("claim {topic}"),
906                    meta,
907                )?;
908            }
909        }
910        Ok(ClaimOutcome::Claimed { token, expires_at })
911    }
912
913    /// 13a (13.3): renew a claim for `ttl` seconds from now (its lease by
914    /// default). [`ClaimStatus::Lost`] when it lapsed or isn't the token's.
915    pub fn renew(&mut self, topic: &str, token: &str, ttl: Option<i64>) -> Result<ClaimStatus> {
916        if self.read_only {
917            return Err(MnemoError::ReadOnly);
918        }
919        let now = self.coordination_now();
920        let Some(mut m) = self.find_claim(topic)? else {
921            return Ok(ClaimStatus::Lost);
922        };
923        if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
924            return Ok(ClaimStatus::Lost);
925        }
926        let lease = match ttl {
927            Some(t) => check_ttl(Some(t))?,
928            None => meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
929        };
930        let expires_at = now + lease;
931        m.metadata
932            .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
933        m.metadata
934            .insert(MNEMO_META_LEASE.into(), Value::from(lease));
935        m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
936        self.put(m)?;
937        Ok(ClaimStatus::Held { expires_at })
938    }
939
940    /// 13a (13.3): release a claim. [`ClaimStatus::Lost`] when it already
941    /// lapsed or isn't the token's (then nothing changes).
942    pub fn release(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
943        if self.read_only {
944            return Err(MnemoError::ReadOnly);
945        }
946        let now = self.coordination_now();
947        let Some(mut m) = self.find_claim(topic)? else {
948            return Ok(ClaimStatus::Lost);
949        };
950        if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
951            return Ok(ClaimStatus::Lost);
952        }
953        m.metadata.remove(MNEMO_META_CLAIM_TOKEN);
954        m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
955        m.metadata
956            .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
957        self.put(m)?;
958        Ok(ClaimStatus::Released)
959    }
960
961    /// 13a (13.3): whether `token` still holds `topic`. Call it before an
962    /// irreversible step. Reads only.
963    pub fn check_claim(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
964        let now = self.coordination_now();
965        let Some(m) = self.find_claim(topic)? else {
966            return Ok(ClaimStatus::Lost);
967        };
968        if meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
969            return Ok(ClaimStatus::Lost);
970        }
971        match effective_expiry(&m, now) {
972            Some(e) if now < e => Ok(ClaimStatus::Held { expires_at: e }),
973            _ => Ok(ClaimStatus::Lost),
974        }
975    }
976
977    /// 13a (13.3): the live claims, by topic. Reads only.
978    pub fn claims(&mut self) -> Result<Vec<Claim>> {
979        let now = self.coordination_now();
980        let mut out: Vec<Claim> = self
981            .coordination_records(MNEMO_META_KIND_CLAIM, None)?
982            .iter()
983            .filter(|m| is_live(m, now))
984            .map(|m| Claim {
985                topic: meta_string(m, MNEMO_META_TOPIC).unwrap_or_default(),
986                holder: meta_string(m, MNEMO_META_HOLDER).unwrap_or_default(),
987                expires_at: effective_expiry(m, now).unwrap_or(now),
988                lease: meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
989            })
990            .collect();
991        out.sort_by(|a, b| a.topic.cmp(&b.topic));
992        Ok(out)
993    }
994
995    /// 13a (13.3): record that this handle's author is active, with its
996    /// `role` and `tool`: its presence record's `last_active`, changed in
997    /// place, at most once a minute (sooner when the role, the tool or the
998    /// presence lock changed). Call it before a write the agent makes
999    /// anyway, so it rides that commit. `false` when nothing was written
1000    /// (too soon, or no author).
1001    pub fn touch_presence(&mut self, role: Option<&str>, tool: Option<&str>) -> Result<bool> {
1002        if self.read_only {
1003            return Err(MnemoError::ReadOnly);
1004        }
1005        let Some(agent) = self.author.clone() else {
1006            return Ok(false);
1007        };
1008        let now = self.coordination_now();
1009        let existing = self
1010            .coordination_records(MNEMO_META_KIND_PRESENCE, Some(&agent))?
1011            .into_iter()
1012            .next();
1013        let role_v = role.map(|r| Value::String(r.to_string()));
1014        let tool_v = tool.map(|t| Value::String(t.to_string()));
1015        // RB-012.4: only a process holding the presence lock writes the
1016        // lock flag and the tool; another (the CLI, beside a server that
1017        // holds it) moves `last_active` alone.
1018        let defer = !self.presence_held
1019            && existing.as_ref().is_some_and(|m| {
1020                m.metadata
1021                    .get(MNEMO_META_PRESENCE_LOCK)
1022                    .and_then(Value::as_bool)
1023                    .unwrap_or(false)
1024            });
1025        if let Some(m) = &existing {
1026            let fresh = meta_i64(m, MNEMO_META_LAST_ACTIVE)
1027                .is_some_and(|t| now >= t && now - t < PRESENCE_EVERY_SECS);
1028            let same = defer
1029                || (m.metadata.get(crate::memory::MNEMO_META_ROLE) == role_v.as_ref()
1030                    && m.metadata.get(MNEMO_META_TOOL) == tool_v.as_ref()
1031                    && m.metadata
1032                        .get(MNEMO_META_PRESENCE_LOCK)
1033                        .and_then(Value::as_bool)
1034                        == Some(self.presence_held));
1035            if fresh && same {
1036                return Ok(false);
1037            }
1038        }
1039        if defer {
1040            let mut m = existing.expect("checked");
1041            m.metadata
1042                .insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1043            self.put(m)?;
1044            return Ok(true);
1045        }
1046        let mut meta = existing
1047            .as_ref()
1048            .map(|m| m.metadata.clone())
1049            .unwrap_or_default();
1050        meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.clone()));
1051        for (k, v) in [
1052            (crate::memory::MNEMO_META_ROLE, role_v),
1053            (MNEMO_META_TOOL, tool_v),
1054        ] {
1055            match v {
1056                Some(v) => {
1057                    meta.insert(k.into(), v);
1058                }
1059                None => {
1060                    meta.remove(k);
1061                }
1062            }
1063        }
1064        meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1065        meta.insert(
1066            MNEMO_META_PRESENCE_LOCK.into(),
1067            Value::Bool(self.presence_held),
1068        );
1069        match existing {
1070            Some(mut m) => {
1071                m.metadata = meta;
1072                self.put(m)?;
1073            }
1074            None => {
1075                self.put_coordination_with_id(
1076                    Ulid::new(),
1077                    MNEMO_META_KIND_PRESENCE,
1078                    format!("presence {agent}"),
1079                    meta,
1080                )?;
1081            }
1082        }
1083        Ok(true)
1084    }
1085
1086    /// 13a (13.3): every agent with a presence record, most recently active
1087    /// first: its role, tool, `last_active`, whether its process is alive
1088    /// (by its presence lock; [`Alive::Unknown`] for an agent with no
1089    /// long-lived process), and the topics it holds. Reads only.
1090    pub fn who(&mut self) -> Result<Vec<Presence>> {
1091        let claims = self.claims()?;
1092        let records = self.coordination_records(MNEMO_META_KIND_PRESENCE, None)?;
1093        let mut out: Vec<Presence> = records
1094            .iter()
1095            .map(|m| {
1096                let agent = meta_string(m, MNEMO_META_AGENT).unwrap_or_default();
1097                let locked = m
1098                    .metadata
1099                    .get(MNEMO_META_PRESENCE_LOCK)
1100                    .and_then(Value::as_bool)
1101                    .unwrap_or(false);
1102                let alive = if !locked {
1103                    Alive::Unknown
1104                } else {
1105                    match crate::shared::probe_presence(&self.path, &agent) {
1106                        Some(true) => Alive::Yes,
1107                        Some(false) => Alive::No,
1108                        None => Alive::Unknown,
1109                    }
1110                };
1111                Presence {
1112                    claims: claims
1113                        .iter()
1114                        .filter(|c| c.holder == agent)
1115                        .map(|c| c.topic.clone())
1116                        .collect(),
1117                    role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1118                    tool: meta_string(m, MNEMO_META_TOOL),
1119                    last_active: meta_i64(m, MNEMO_META_LAST_ACTIVE).unwrap_or(0),
1120                    alive,
1121                    agent,
1122                }
1123            })
1124            .collect();
1125        out.sort_by(|a, b| {
1126            b.last_active
1127                .cmp(&a.last_active)
1128                .then(a.agent.cmp(&b.agent))
1129        });
1130        Ok(out)
1131    }
1132}
1133
1134// --- 13a step 4: tasks (13.1) ------------------------------------------------
1135
1136use crate::memory::{
1137    task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_KIND_TASK, MNEMO_META_OWNER,
1138    MNEMO_META_PRE_APPROVED, MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_SLUG_MAX, TASK_TRANSITIONS,
1139};
1140
1141/// 13a (13.1): a task to add ([`Mnemo::task_add`]).
1142#[derive(Debug, Clone, Default, PartialEq, Eq)]
1143#[non_exhaustive]
1144pub struct TaskSpec {
1145    /// One line, at most 200 bytes.
1146    pub title: String,
1147    /// At most 8 KB; put more in a fact and name it.
1148    pub body: String,
1149    /// The role that may take it (`worker`); `None`, any.
1150    pub role: Option<String>,
1151    /// The slugs of the tasks it waits for; each must exist.
1152    pub after: Vec<String>,
1153    /// Its owner may go from `ready` to `done` without the creator.
1154    pub pre_approved: bool,
1155    /// Its name; made from the title when left out.
1156    pub slug: Option<String>,
1157    /// v0.18.1: what it's about: finding ids (`RB-014.1`), files, PRs. Each
1158    /// is one line, at most 200 bytes, and at most 32 of them.
1159    pub refs: Vec<String>,
1160}
1161
1162impl TaskSpec {
1163    /// v0.19.0: a task titled `title`, for any role, waiting for nothing.
1164    /// The type is `#[non_exhaustive]`, so outside this crate set the other
1165    /// fields after this (`spec.role = Some("worker".into())`).
1166    pub fn new(title: impl Into<String>) -> Self {
1167        TaskSpec {
1168            title: title.into(),
1169            ..Default::default()
1170        }
1171    }
1172}
1173
1174/// v0.18.1: the most refs a task carries, and the longest one, in bytes.
1175const TASK_REFS_MAX: usize = 32;
1176const TASK_REF_MAX: usize = 200;
1177
1178/// 13a (13.1): one task.
1179#[derive(Debug, Clone, PartialEq)]
1180#[non_exhaustive]
1181pub struct Task {
1182    /// The record's id.
1183    pub id: Ulid,
1184    /// Its name.
1185    pub slug: String,
1186    /// One line.
1187    pub title: String,
1188    /// The body (may be empty).
1189    pub body: String,
1190    /// The role that may take it.
1191    pub role: Option<String>,
1192    /// `queued`, `active`, `ready`, `done` or `blocked`.
1193    pub status: String,
1194    /// The agent that took it.
1195    pub owner: Option<String>,
1196    /// The agent that added it.
1197    pub creator: String,
1198    /// The slugs it waits for.
1199    pub after: Vec<String>,
1200    /// Whether its owner may set `done`.
1201    pub pre_approved: bool,
1202    /// v0.18.1: what it's about (`_mnemo.refs`); empty when it names none.
1203    pub refs: Vec<String>,
1204    /// When it was added, in unix seconds.
1205    pub created_at: i64,
1206    /// Its status changes and notes, oldest first (`from`, `to`, `at`,
1207    /// `by`, and `note` or `reclaimed_from` when there's one).
1208    pub history: Vec<Value>,
1209}
1210
1211impl Task {
1212    /// The task a record holds, if it's one.
1213    pub fn from_memory(m: &Memory) -> Option<Task> {
1214        if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(MNEMO_META_KIND_TASK) {
1215            return None;
1216        }
1217        let (title, body) = match m.content.split_once("\n\n") {
1218            Some((a, b)) => (a.to_string(), b.to_string()),
1219            None => (m.content.clone(), String::new()),
1220        };
1221        Some(Task {
1222            id: m.id,
1223            slug: meta_string(m, MNEMO_META_SLUG).unwrap_or_default(),
1224            title,
1225            body,
1226            role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1227            status: meta_string(m, MNEMO_META_STATUS).unwrap_or_default(),
1228            owner: meta_string(m, MNEMO_META_OWNER),
1229            creator: meta_string(m, MNEMO_META_CREATOR).unwrap_or_default(),
1230            after: m
1231                .metadata
1232                .get(MNEMO_META_AFTER)
1233                .and_then(Value::as_array)
1234                .map(|a| {
1235                    a.iter()
1236                        .filter_map(|v| v.as_str().map(str::to_string))
1237                        .collect()
1238                })
1239                .unwrap_or_default(),
1240            pre_approved: m
1241                .metadata
1242                .get(MNEMO_META_PRE_APPROVED)
1243                .and_then(Value::as_bool)
1244                .unwrap_or(false),
1245            refs: m
1246                .metadata
1247                .get(crate::memory::MNEMO_META_REFS)
1248                .and_then(Value::as_array)
1249                .map(|a| {
1250                    a.iter()
1251                        .filter_map(|v| v.as_str().map(str::to_string))
1252                        .collect()
1253                })
1254                .unwrap_or_default(),
1255            created_at: m.created_at,
1256            history: m
1257                .metadata
1258                .get(MNEMO_META_STATUS_HISTORY)
1259                .and_then(Value::as_array)
1260                .cloned()
1261                .unwrap_or_default(),
1262        })
1263    }
1264
1265    /// Whether an agent of `role` may take it (a task with no role is any
1266    /// role's).
1267    fn for_role(&self, role: Option<&str>) -> bool {
1268        self.role.is_none() || self.role.as_deref() == role
1269    }
1270}
1271
1272/// 13a (13.1): a task [`Mnemo::task_next`] took, with its claim's token.
1273#[derive(Debug, Clone, PartialEq)]
1274#[non_exhaustive]
1275pub struct TaskTaken {
1276    /// The task, now `active` and this agent's.
1277    pub task: Task,
1278    /// The `task:<slug>` claim's token (give it to `task_update` for the
1279    /// strict check).
1280    pub token: String,
1281    /// When the claim lapses unless an update renews it.
1282    pub expires_at: i64,
1283    /// The owner whose claim lapsed, when this took an abandoned task back.
1284    pub reclaimed_from: Option<String>,
1285}
1286
1287/// 13a (13.1): the claim an owner holds after a [`Mnemo::task_update`]
1288/// (RB-012.1), so it always has the current token.
1289#[derive(Debug, Clone, PartialEq, Eq)]
1290#[non_exhaustive]
1291pub struct TaskClaim {
1292    /// The `task:<slug>` claim's token.
1293    pub token: String,
1294    /// When it lapses unless an update renews it.
1295    pub expires_at: i64,
1296    /// The claim had lapsed and nobody took the task, so the owner took
1297    /// the claim again (with a new token).
1298    pub retaken: bool,
1299}
1300
1301/// 13a (13.1): why a [`Mnemo::task_update`] changed nothing.
1302#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1303pub enum TaskLost {
1304    /// Another agent took the task back after the caller's claim lapsed.
1305    TakenBack,
1306    /// The token isn't the task's claim's (another session of the same
1307    /// agent may hold it).
1308    OtherToken,
1309}
1310
1311/// 13a (13.1): what [`Mnemo::task_update`] did.
1312#[derive(Debug, Clone, PartialEq)]
1313pub enum TaskOutcome {
1314    /// Changed (or a note added). For the owner, the claim it now holds:
1315    /// renewed, or taken again after a lapse; `None` when the change
1316    /// released it (`ready`, `done`, `queued`) or wasn't the owner's.
1317    Updated(Box<Task>, Option<TaskClaim>),
1318    /// Nothing changed: don't carry on with it.
1319    Lost(TaskLost),
1320}
1321
1322/// The slug a title gives: lower case, runs of anything but `a-z0-9`
1323/// as one `-`, at most [`TASK_SLUG_MAX`] bytes.
1324pub fn slug_of(title: &str) -> String {
1325    let mut out = String::new();
1326    for c in title.chars() {
1327        if c.is_ascii_alphanumeric() {
1328            out.push(c.to_ascii_lowercase());
1329        } else if !out.ends_with('-') && !out.is_empty() {
1330            out.push('-');
1331        }
1332        if out.len() >= TASK_SLUG_MAX {
1333            break;
1334        }
1335    }
1336    out.trim_end_matches('-').to_string()
1337}
1338
1339fn valid_slug(s: &str) -> bool {
1340    !s.is_empty()
1341        && s.len() <= TASK_SLUG_MAX
1342        && s.bytes()
1343            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
1344}
1345
1346fn task_topic(slug: &str) -> String {
1347    format!("task:{slug}")
1348}
1349
1350impl Mnemo {
1351    fn task_records(&mut self, slug: Option<&str>) -> Result<Vec<Memory>> {
1352        let mut v = self.coordination_records(MNEMO_META_KIND_TASK, slug)?;
1353        v.sort_by_key(|m| m.created_at);
1354        Ok(v)
1355    }
1356
1357    fn task_record(&mut self, slug: &str) -> Result<Option<Memory>> {
1358        Ok(self.task_records(Some(slug))?.into_iter().next())
1359    }
1360
1361    /// 13a (13.1): one task by slug. Reads only.
1362    pub fn task(&mut self, slug: &str) -> Result<Option<Task>> {
1363        Ok(self.task_record(slug)?.as_ref().and_then(Task::from_memory))
1364    }
1365
1366    /// 13a (13.1): the tasks, oldest first, with `status` and for `role`
1367    /// when given (a task with no role matches any). Reads only.
1368    pub fn tasks(&mut self, status: Option<&str>, role: Option<&str>) -> Result<Vec<Task>> {
1369        Ok(self
1370            .task_records(None)?
1371            .iter()
1372            .filter_map(Task::from_memory)
1373            .filter(|t| status.is_none_or(|s| t.status == s))
1374            .filter(|t| role.is_none() || t.for_role(role))
1375            .collect())
1376    }
1377
1378    /// 13a (13.1): the `queued` tasks an agent of `role` may take now (all
1379    /// their `after` tasks `done`), oldest first. Reads only.
1380    pub fn ready_tasks(&mut self, role: Option<&str>) -> Result<Vec<Task>> {
1381        let all: Vec<Task> = self
1382            .task_records(None)?
1383            .iter()
1384            .filter_map(Task::from_memory)
1385            .collect();
1386        let done: std::collections::HashSet<&str> = all
1387            .iter()
1388            .filter(|t| t.status == task_status::DONE)
1389            .map(|t| t.slug.as_str())
1390            .collect();
1391        Ok(all
1392            .iter()
1393            .filter(|t| t.status == task_status::QUEUED && t.for_role(role))
1394            .filter(|t| t.after.iter().all(|a| done.contains(a.as_str())))
1395            .cloned()
1396            .collect())
1397    }
1398
1399    /// 13a (13.1): add a task, `queued`, created by this handle's author.
1400    /// A slug that already names a task updates its title, body, role,
1401    /// `after` and `pre_approved` in place (its status, owner and history
1402    /// stay); `Unchanged` when nothing differs. `after` must name existing
1403    /// tasks, never itself.
1404    pub fn task_add(&mut self, spec: &TaskSpec) -> Result<(Task, WriteOutcome)> {
1405        if self.read_only {
1406            return Err(MnemoError::ReadOnly);
1407        }
1408        let title = spec.title.trim();
1409        if title.is_empty()
1410            || title.contains('\n')
1411            || title.len() > crate::memory::MESSAGE_SUBJECT_MAX
1412        {
1413            return Err(MnemoError::Invalid(format!(
1414                "a task's title is one line, not empty, at most {} bytes",
1415                crate::memory::MESSAGE_SUBJECT_MAX
1416            )));
1417        }
1418        if spec.body.len() > crate::memory::MESSAGE_BODY_MAX {
1419            return Err(MnemoError::Invalid(format!(
1420                "a task's body is at most {} bytes; put more in a fact and name it",
1421                crate::memory::MESSAGE_BODY_MAX
1422            )));
1423        }
1424        let slug = match &spec.slug {
1425            Some(s) => s.clone(),
1426            None => slug_of(title),
1427        };
1428        if !valid_slug(&slug) {
1429            return Err(MnemoError::Invalid(format!(
1430                "{slug:?} isn't a slug: 1 to {TASK_SLUG_MAX} of a-z, 0-9, '.', '_' and '-' \
1431                 (give one with --slug)"
1432            )));
1433        }
1434        if let Some(r) = &spec.role {
1435            if !crate::memory::valid_agent_id(r) {
1436                return Err(MnemoError::Invalid(format!("{r:?} isn't a role")));
1437            }
1438        }
1439        if spec.refs.len() > TASK_REFS_MAX
1440            || spec
1441                .refs
1442                .iter()
1443                .any(|r| r.trim().is_empty() || r.contains('\n') || r.len() > TASK_REF_MAX)
1444        {
1445            return Err(MnemoError::Invalid(format!(
1446                "a task's refs: at most {TASK_REFS_MAX}, each one line, not empty, at most \
1447                 {TASK_REF_MAX} bytes"
1448            )));
1449        }
1450        for a in &spec.after {
1451            if a == &slug {
1452                return Err(MnemoError::Invalid("a task can't wait for itself".into()));
1453            }
1454            if self.task_record(a)?.is_none() {
1455                return Err(MnemoError::Invalid(format!("after: no task {a:?}")));
1456            }
1457        }
1458        let content = if spec.body.is_empty() {
1459            title.to_string()
1460        } else {
1461            format!("{title}\n\n{}", spec.body)
1462        };
1463        let set = |meta: &mut Map<String, Value>| {
1464            match &spec.role {
1465                Some(r) => {
1466                    meta.insert(
1467                        crate::memory::MNEMO_META_ROLE.into(),
1468                        Value::String(r.clone()),
1469                    );
1470                }
1471                None => {
1472                    meta.remove(crate::memory::MNEMO_META_ROLE);
1473                }
1474            }
1475            meta.insert(
1476                MNEMO_META_AFTER.into(),
1477                Value::Array(
1478                    spec.after
1479                        .iter()
1480                        .map(|a| Value::String(a.clone()))
1481                        .collect(),
1482                ),
1483            );
1484            meta.insert(
1485                MNEMO_META_PRE_APPROVED.into(),
1486                Value::Bool(spec.pre_approved),
1487            );
1488            // v0.18.1: only when there are refs, so re-adding an older task
1489            // as it was is still a no-op.
1490            if spec.refs.is_empty() {
1491                meta.remove(crate::memory::MNEMO_META_REFS);
1492            } else {
1493                meta.insert(
1494                    crate::memory::MNEMO_META_REFS.into(),
1495                    Value::Array(
1496                        spec.refs
1497                            .iter()
1498                            .map(|r| Value::String(r.trim().to_string()))
1499                            .collect(),
1500                    ),
1501                );
1502            }
1503        };
1504        if let Some(mut m) = self.task_record(&slug)? {
1505            let t = Task::from_memory(&m).expect("a task");
1506            let mut meta = m.metadata.clone();
1507            set(&mut meta);
1508            if meta == m.metadata && m.content == content {
1509                return Ok((t, WriteOutcome::Unchanged));
1510            }
1511            // RB-012.2: a finished task is never reopened by a re-add, and
1512            // only its creator changes what a task is.
1513            if t.status == task_status::DONE {
1514                let mut n = 2;
1515                while self.task_record(&format!("{slug}-{n}"))?.is_some() {
1516                    n += 1;
1517                }
1518                return Err(MnemoError::Invalid(format!(
1519                    "{slug} is done; give a new slug ({slug}-{n}?)"
1520                )));
1521            }
1522            let caller = self.author.clone().unwrap_or_else(|| "anonymous".into());
1523            if caller != t.creator {
1524                return Err(MnemoError::Invalid(format!(
1525                    "that slug is {}'s task; it wasn't changed",
1526                    t.creator
1527                )));
1528            }
1529            // RB-012.6 item 5: an `after` that closes a cycle.
1530            if self.closes_cycle(&slug, &spec.after)? {
1531                return Err(MnemoError::Invalid(format!(
1532                    "after: that would make {slug} wait for itself, through the tasks it waits for"
1533                )));
1534            }
1535            m.metadata = meta;
1536            m.content = content;
1537            let id = m.id;
1538            self.put(m)?;
1539            let t = Task::from_memory(&self.get(&id)?).expect("a task");
1540            return Ok((t, WriteOutcome::Updated));
1541        }
1542        let mut meta = Map::new();
1543        meta.insert(MNEMO_META_SLUG.into(), Value::String(slug));
1544        meta.insert(
1545            MNEMO_META_STATUS.into(),
1546            Value::String(task_status::QUEUED.into()),
1547        );
1548        meta.insert(
1549            MNEMO_META_CREATOR.into(),
1550            Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
1551        );
1552        meta.insert(
1553            MNEMO_META_DELIVERY.into(),
1554            Value::String(crate::memory::delivery::SENT.into()),
1555        );
1556        set(&mut meta);
1557        let id = self.put_coordination_with_id(Ulid::new(), MNEMO_META_KIND_TASK, content, meta)?;
1558        let t = Task::from_memory(&self.get(&id)?).expect("a task");
1559        Ok((t, WriteOutcome::Added))
1560    }
1561
1562    /// Whether `slug` waiting for `after` closes a cycle: a task in `after`
1563    /// that waits (through its own `after`, transitively) for `slug`.
1564    fn closes_cycle(&mut self, slug: &str, after: &[String]) -> Result<bool> {
1565        let all: std::collections::HashMap<String, Vec<String>> = self
1566            .task_records(None)?
1567            .iter()
1568            .filter_map(Task::from_memory)
1569            .map(|t| (t.slug, t.after))
1570            .collect();
1571        let mut stack: Vec<&str> = after.iter().map(String::as_str).collect();
1572        let mut seen = std::collections::HashSet::new();
1573        while let Some(s) = stack.pop() {
1574            if s == slug {
1575                return Ok(true);
1576            }
1577            if seen.insert(s.to_string()) {
1578                if let Some(next) = all.get(s) {
1579                    stack.extend(next.iter().map(String::as_str));
1580                }
1581            }
1582        }
1583        Ok(false)
1584    }
1585
1586    /// Append a `status_history` entry.
1587    pub(super) fn task_history(
1588        m: &mut Memory,
1589        from: &str,
1590        to: &str,
1591        by: &str,
1592        at: i64,
1593        extra: &[(&str, &str)],
1594    ) {
1595        let mut e = Map::new();
1596        e.insert("from".into(), Value::String(from.into()));
1597        e.insert("to".into(), Value::String(to.into()));
1598        e.insert("at".into(), Value::from(at));
1599        e.insert("by".into(), Value::String(by.into()));
1600        for (k, v) in extra {
1601            e.insert((*k).into(), Value::String((*v).into()));
1602        }
1603        let mut h = m
1604            .metadata
1605            .get(MNEMO_META_STATUS_HISTORY)
1606            .and_then(Value::as_array)
1607            .cloned()
1608            .unwrap_or_default();
1609        h.push(Value::Object(e));
1610        m.metadata
1611            .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(h));
1612    }
1613
1614    /// 13a (13.1): take the next task for `role`, for this handle's author,
1615    /// all in one exclusive window in a shared handle: the oldest `queued`
1616    /// task for the role whose `after` tasks are all `done`; failing that
1617    /// (R-010.7), an `active` one whose `task:<slug>` claim has lapsed,
1618    /// taken back from its owner with a `status_history` entry naming it.
1619    /// It claims `task:<slug>` for [`crate::memory::TASK_CLAIM_TTL`] and
1620    /// sets `active` and the owner. `None` when there's nothing to take.
1621    pub fn task_next(&mut self, role: Option<&str>) -> Result<Option<TaskTaken>> {
1622        if self.read_only {
1623            return Err(MnemoError::ReadOnly);
1624        }
1625        let agent = self.claim_agent()?;
1626        let now = self.coordination_now();
1627        let ready: Vec<Ulid> = self.ready_tasks(role)?.iter().map(|t| t.id).collect();
1628        // Taken tasks (`active`, or `blocked`: RB-012.3) for the role. The
1629        // caller's own come first (RB-012.1): a worker whose claim lapsed
1630        // gets its own task back before anything new. `claim()` decides
1631        // which are free.
1632        let taken: Vec<Task> = self
1633            .task_records(None)?
1634            .iter()
1635            .filter_map(Task::from_memory)
1636            .filter(|t| t.status == task_status::ACTIVE || t.status == task_status::BLOCKED)
1637            .filter(|t| t.for_role(role))
1638            .collect();
1639        let (own, others): (Vec<&Task>, Vec<&Task>) = taken
1640            .iter()
1641            .partition(|t| t.owner.as_deref() == Some(agent.as_str()));
1642        for (id, back) in own
1643            .iter()
1644            .map(|t| (t.id, true))
1645            .chain(ready.into_iter().map(|i| (i, false)))
1646            .chain(others.iter().map(|t| (t.id, true)))
1647        {
1648            let mut m = self.get(&id)?;
1649            let t = Task::from_memory(&m).expect("a task");
1650            let (token, expires_at) =
1651                match self.claim(&task_topic(&t.slug), Some(TASK_CLAIM_TTL))? {
1652                    ClaimOutcome::Claimed { token, expires_at } => (token, expires_at),
1653                    ClaimOutcome::HeldBy { .. } => continue,
1654                };
1655            // The claim's write may have changed the catalog: read the task
1656            // again before changing it.
1657            m = self.get(&id)?;
1658            let old = t.owner.clone();
1659            let own = old.as_deref() == Some(agent.as_str());
1660            if back && own {
1661                Self::task_history(
1662                    &mut m,
1663                    &t.status,
1664                    task_status::ACTIVE,
1665                    &agent,
1666                    now,
1667                    &[("note", "taken again after its claim lapsed")],
1668                );
1669            } else if back {
1670                let from = old.clone().unwrap_or_default();
1671                Self::task_history(
1672                    &mut m,
1673                    &t.status,
1674                    task_status::ACTIVE,
1675                    &agent,
1676                    now,
1677                    &[("reclaimed_from", from.as_str())],
1678                );
1679            } else {
1680                Self::task_history(
1681                    &mut m,
1682                    task_status::QUEUED,
1683                    task_status::ACTIVE,
1684                    &agent,
1685                    now,
1686                    &[],
1687                );
1688            }
1689            m.metadata.insert(
1690                MNEMO_META_STATUS.into(),
1691                Value::String(task_status::ACTIVE.into()),
1692            );
1693            m.metadata
1694                .insert(MNEMO_META_OWNER.into(), Value::String(agent.clone()));
1695            self.put(m)?;
1696            let task = Task::from_memory(&self.get(&id)?).expect("a task");
1697            return Ok(Some(TaskTaken {
1698                task,
1699                token,
1700                expires_at,
1701                reclaimed_from: if back && !own { old } else { None },
1702            }));
1703        }
1704        Ok(None)
1705    }
1706
1707    /// 13a (13.1): change a task's status (along [`TASK_TRANSITIONS`]), or
1708    /// add a `note` with none, as this handle's author.
1709    /// - **Its owner** moves it from `active` to `ready`, `blocked` or
1710    ///   `queued` (handing it back) and from `blocked` to `active`, and may
1711    ///   add notes; each renews its `task:<slug>` claim. With a `token`,
1712    ///   the claim must be that token's. An owner whose task was taken back
1713    ///   (or whose token isn't the claim's) gets [`TaskOutcome::Lost`].
1714    /// - **`ready → done`** is its creator's, or its owner's when
1715    ///   `pre_approved`.
1716    /// - **`active → queued`** is anyone's once the owner's claim has
1717    ///   lapsed (an abandoned task).
1718    /// - `queued → active` happens only through [`Mnemo::task_next`].
1719    ///
1720    /// `ready`, `done` and `queued` release the claim.
1721    pub fn task_update(
1722        &mut self,
1723        slug: &str,
1724        status: Option<&str>,
1725        note: Option<&str>,
1726        token: Option<&str>,
1727    ) -> Result<TaskOutcome> {
1728        if self.read_only {
1729            return Err(MnemoError::ReadOnly);
1730        }
1731        let agent = self.claim_agent()?;
1732        let now = self.coordination_now();
1733        let Some(m) = self.task_record(slug)? else {
1734            return Err(MnemoError::Invalid(format!("no task {slug:?}")));
1735        };
1736        let t = Task::from_memory(&m).expect("a task");
1737        let to = status.unwrap_or(&t.status).to_string();
1738        if status.is_none() && note.is_none() {
1739            return Err(MnemoError::Invalid("give a status or a note".into()));
1740        }
1741        // A token says the caller thinks the task is its own: when it isn't
1742        // any more, that's the answer, whatever the change asked for.
1743        if token.is_some() && t.owner.as_deref() != Some(agent.as_str()) {
1744            return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1745        }
1746        let changing = to != t.status;
1747        if changing && !TASK_TRANSITIONS.contains(&(t.status.as_str(), to.as_str())) {
1748            return Err(MnemoError::Invalid(format!(
1749                "a task can't go from {} to {to}",
1750                t.status
1751            )));
1752        }
1753        if changing && t.status == task_status::QUEUED {
1754            return Err(MnemoError::Invalid(
1755                "a queued task is taken with `task next`".into(),
1756            ));
1757        }
1758        let topic = task_topic(slug);
1759        let claim = self.find_claim(&topic)?;
1760        let live = claim.as_ref().filter(|c| is_live(c, now));
1761        let claim_token = claim
1762            .as_ref()
1763            .and_then(|c| meta_string(c, MNEMO_META_CLAIM_TOKEN));
1764        let held_by_owner = live.is_some_and(|c| meta_string(c, MNEMO_META_HOLDER) == t.owner);
1765        let is_owner = t.owner.as_deref() == Some(agent.as_str());
1766        let is_creator = t.creator == agent;
1767        // Who may do this.
1768        let by_owner = if changing && t.status == task_status::READY {
1769            // ready -> done
1770            if !(is_creator || (is_owner && t.pre_approved)) {
1771                return Err(MnemoError::Invalid(format!(
1772                    "{slug} waits for its creator ({}) to set done",
1773                    t.creator
1774                )));
1775            }
1776            false
1777        } else if changing && to == task_status::QUEUED && !is_owner {
1778            // Requeueing an abandoned task: anyone's, once its claim lapsed.
1779            if let Some(c) = live {
1780                return Err(MnemoError::Invalid(format!(
1781                    "{slug} is {}'s, and its claim is live until {}; only its owner can hand \
1782                     it back before then",
1783                    t.owner.as_deref().unwrap_or("its owner"),
1784                    crate::memory::date_time_of(effective_expiry(c, now).unwrap_or(now))
1785                )));
1786            }
1787            false
1788        } else if t.status == task_status::DONE || (!changing && t.status == task_status::READY) {
1789            // A note on a finished task: its creator's or owner's.
1790            if !(is_creator || is_owner) {
1791                return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1792            }
1793            false
1794        } else if !changing && is_creator && !is_owner {
1795            false // its creator's note, at any status
1796        } else if t.status == task_status::QUEUED {
1797            // A note on a queued task: its creator's.
1798            if !is_creator {
1799                return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1800            }
1801            false
1802        } else {
1803            if !is_owner {
1804                return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1805            }
1806            true
1807        };
1808        // The owner's claim (RB-012.1):
1809        // - live and its own: a given token must be the claim's;
1810        // - live and someone else's: taken back;
1811        // - lapsed: a given token must be the lapsed claim's (the record
1812        //   keeps it), else another session took it in between; then the
1813        //   owner carries on and takes the claim again.
1814        let mut renew_token = None;
1815        if by_owner {
1816            let token_ok = token.is_none_or(|tk| claim_token.as_deref() == Some(tk));
1817            if live.is_some() && !held_by_owner {
1818                return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1819            }
1820            if !token_ok {
1821                return Ok(TaskOutcome::Lost(TaskLost::OtherToken));
1822            }
1823            if held_by_owner {
1824                renew_token = claim_token.clone();
1825            }
1826        }
1827        let mut m = m;
1828        let mut extra: Vec<(&str, &str)> = Vec::new();
1829        if let Some(n) = note {
1830            extra.push(("note", n));
1831        }
1832        Self::task_history(&mut m, &t.status, &to, &agent, now, &extra);
1833        m.metadata
1834            .insert(MNEMO_META_STATUS.into(), Value::String(to.clone()));
1835        if to == task_status::QUEUED {
1836            m.metadata.remove(MNEMO_META_OWNER);
1837        }
1838        let id = m.id;
1839        self.put(m)?;
1840        let releases =
1841            [task_status::READY, task_status::DONE, task_status::QUEUED].contains(&to.as_str());
1842        let mut held: Option<TaskClaim> = None;
1843        match (releases, by_owner, renew_token) {
1844            (true, _, Some(tk)) => {
1845                self.release(&topic, &tk)?;
1846            }
1847            (true, _, None) => {
1848                // A lapsed or foreign-free claim: let it lapse.
1849                if let Some(mut c) = self.find_claim(&topic)? {
1850                    if is_live(&c, now)
1851                        && meta_string(&c, MNEMO_META_HOLDER) == t.owner
1852                        && to == task_status::DONE
1853                    {
1854                        c.metadata.remove(MNEMO_META_CLAIM_TOKEN);
1855                        c.metadata
1856                            .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
1857                        self.put(c)?;
1858                    }
1859                }
1860            }
1861            (false, true, Some(tk)) => {
1862                if let ClaimStatus::Held { expires_at } =
1863                    self.renew(&topic, &tk, Some(TASK_CLAIM_TTL))?
1864                {
1865                    held = Some(TaskClaim {
1866                        token: tk,
1867                        expires_at,
1868                        retaken: false,
1869                    });
1870                }
1871            }
1872            (false, true, None) => {
1873                // Lapsed, and nobody else took it: the owner takes it again,
1874                // and gets the new token.
1875                if let ClaimOutcome::Claimed { token, expires_at } =
1876                    self.claim(&topic, Some(TASK_CLAIM_TTL))?
1877                {
1878                    held = Some(TaskClaim {
1879                        token,
1880                        expires_at,
1881                        retaken: true,
1882                    });
1883                }
1884            }
1885            (false, false, _) => {}
1886        }
1887        Ok(TaskOutcome::Updated(
1888            Box::new(Task::from_memory(&self.get(&id)?).expect("a task")),
1889            held,
1890        ))
1891    }
1892}
1893
1894// --- 13a step 5: what's new for an agent, and the wake-up guardrails ---------
1895
1896use crate::memory::{
1897    HOP_CAP, MNEMO_META_WAKES, MNEMO_META_WAKE_PAUSED, MNEMO_META_WARNED_EXPIRY, PAIR_BURST,
1898    PAIR_BURST_SECS, TASK_CLAIM_WARN_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
1899};
1900
1901/// 13a (13.1b): what's new for an agent since it was last shown
1902/// ([`Mnemo::new_work`]), for the per-turn hook.
1903#[derive(Debug, Clone, Default, PartialEq)]
1904#[non_exhaustive]
1905pub struct NewWork {
1906    /// Unread messages to it, its role or everyone, not yet `seen`.
1907    pub messages: Vec<Message>,
1908    /// Tasks ready for its role, not yet `seen`.
1909    pub tasks: Vec<Task>,
1910    /// Its own task claims lapsing within
1911    /// [`crate::memory::TASK_CLAIM_WARN_SECS`], not yet warned about at this
1912    /// expiry.
1913    pub lapsing: Vec<Claim>,
1914    /// READY-NOTICE (v0.17.2): tasks it created that are `ready`, waiting
1915    /// for its `done`, not yet shown to it as such. They wait for a
1916    /// review, so they never wake a session.
1917    pub ready_for_done: Vec<Task>,
1918    /// v0.18.0: for an agent of role `planner`, the `open` findings not
1919    /// yet shown to it (`_mnemo.seen_by`). They wait for its triage, so
1920    /// they never wake a session.
1921    pub findings: Vec<super::Finding>,
1922    /// The agent it was read for: [`Mnemo::mark_shown`] records this agent
1923    /// as having seen the broadcasts and the role's tasks.
1924    pub agent: Option<String>,
1925}
1926
1927impl NewWork {
1928    /// Whether there's nothing.
1929    pub fn is_empty(&self) -> bool {
1930        self.messages.is_empty()
1931            && self.tasks.is_empty()
1932            && self.lapsing.is_empty()
1933            && self.ready_for_done.is_empty()
1934            && self.findings.is_empty()
1935    }
1936}
1937
1938/// 13a (13.1b): what [`Mnemo::wake`] decided.
1939#[derive(Debug, Clone, PartialEq, Eq)]
1940pub enum Wake {
1941    /// Wake the agent for these, now marked `delivered`: how many
1942    /// pre-approved tasks and messages addressed to it by id.
1943    Now {
1944        /// Pre-approved tasks ready for its role.
1945        tasks: usize,
1946        /// Messages to it by id.
1947        messages: usize,
1948    },
1949    /// Nothing that may wake it.
1950    Nothing,
1951    /// Something waits, but a guardrail holds it (its items stay `sent`,
1952    /// and are seen at the next turn or session start).
1953    Held(&'static str),
1954}
1955
1956impl Mnemo {
1957    /// 13a (13.1b): what's new for `agent` (and `role`) since it was last
1958    /// shown. Reads only; [`Mnemo::mark_shown`] records that it was.
1959    pub fn new_work(&mut self, agent: Option<&str>, role: Option<&str>) -> Result<NewWork> {
1960        let now = self.coordination_now();
1961        let unseen =
1962            |d: &str| d == crate::memory::delivery::SENT || d == crate::memory::delivery::DELIVERED;
1963        // RB-012.6 item 4: a message to the agent by id is new until it's
1964        // seen; one to a role or everyone, and a role's task, until this
1965        // agent has been shown it (`_mnemo.seen_by`).
1966        let mut messages = Vec::new();
1967        for msg in self.inbox(agent, role, true)? {
1968            let broadcast = msg.to == "all" || msg.to.starts_with("role:");
1969            let new = match (broadcast, agent) {
1970                (true, Some(a)) => !seen_by(&self.get(&msg.id)?).iter().any(|s| s == a),
1971                _ => unseen(&msg.delivery),
1972            };
1973            if new {
1974                messages.push(msg);
1975            }
1976        }
1977        let mut tasks = Vec::new();
1978        for t in self.ready_tasks(role)? {
1979            let m = self.get(&t.id)?;
1980            let new = match agent {
1981                Some(a) => !seen_by(&m).iter().any(|s| s == a),
1982                None => meta_string(&m, MNEMO_META_DELIVERY).is_none_or(|d| unseen(&d)),
1983            };
1984            if new {
1985                tasks.push(t);
1986            }
1987        }
1988        // READY-NOTICE: its own tasks waiting for its `done`, not yet
1989        // shown to it as such.
1990        let mut ready_for_done = Vec::new();
1991        if let Some(a) = agent {
1992            for t in self.tasks(Some(crate::memory::task_status::READY), None)? {
1993                if t.creator == a && !ready_seen_by(&self.get(&t.id)?).iter().any(|s| s == a) {
1994                    ready_for_done.push(t);
1995                }
1996            }
1997        }
1998        // v0.18.0: the findings waiting for a Planner's triage.
1999        let mut findings = Vec::new();
2000        if let (Some(a), Some("planner")) = (agent, role) {
2001            let open = super::FindingFilter {
2002                status: Some(crate::memory::finding_status::OPEN.into()),
2003                ..Default::default()
2004            };
2005            for f in self.findings(&open)? {
2006                if !seen_by(&self.get(&f.record_id)?).iter().any(|s| s == a) {
2007                    findings.push(f);
2008                }
2009            }
2010        }
2011        let mut lapsing = Vec::new();
2012        if let Some(a) = agent {
2013            for m in self.coordination_records(MNEMO_META_KIND_CLAIM, None)? {
2014                let topic = meta_string(&m, MNEMO_META_TOPIC).unwrap_or_default();
2015                if !topic.starts_with("task:")
2016                    || meta_string(&m, MNEMO_META_HOLDER).as_deref() != Some(a)
2017                    || !is_live(&m, now)
2018                {
2019                    continue;
2020                }
2021                let e = effective_expiry(&m, now).unwrap_or(now);
2022                if e - now <= TASK_CLAIM_WARN_SECS
2023                    && meta_i64(&m, MNEMO_META_WARNED_EXPIRY) != Some(e)
2024                {
2025                    lapsing.push(Claim {
2026                        topic,
2027                        holder: a.to_string(),
2028                        expires_at: e,
2029                        lease: meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
2030                    });
2031                }
2032            }
2033        }
2034        Ok(NewWork {
2035            messages,
2036            tasks,
2037            lapsing,
2038            ready_for_done,
2039            findings,
2040            agent: agent.map(str::to_string),
2041        })
2042    }
2043
2044    /// 13a (13.1b): record that `work` was shown: its messages and tasks
2045    /// `seen`, its tasks waiting for a `done` shown to their creator
2046    /// (READY-NOTICE), its lapsing claims warned about at their expiry. In
2047    /// place.
2048    pub fn mark_shown(&mut self, work: &NewWork) -> Result<()> {
2049        if self.read_only {
2050            return Err(MnemoError::ReadOnly);
2051        }
2052        let ids: Vec<Ulid> = work.messages.iter().map(|m| m.id).collect();
2053        // Seen by the agent the work was read for.
2054        let who = work.agent.clone().or_else(|| self.author.clone());
2055        let author = std::mem::replace(&mut self.author, who.clone());
2056        let r = self.mark_seen(&ids);
2057        self.author = author;
2058        r?;
2059        for t in &work.tasks {
2060            let mut m = self.get(&t.id)?;
2061            match who.clone() {
2062                // Seen by this agent; the task stays new to the others.
2063                Some(a) => {
2064                    if add_seen_by(&mut m, &a) {
2065                        self.put(m)?;
2066                    }
2067                }
2068                None => {
2069                    m.metadata.insert(
2070                        MNEMO_META_DELIVERY.into(),
2071                        Value::String(crate::memory::delivery::SEEN.into()),
2072                    );
2073                    self.put(m)?;
2074                }
2075            }
2076        }
2077        // v0.18.0: the findings shown to the Planner that read them.
2078        if let Some(a) = &who {
2079            for f in &work.findings {
2080                let mut m = self.get(&f.record_id)?;
2081                if add_seen_by(&mut m, a) {
2082                    self.put(m)?;
2083                }
2084            }
2085        }
2086        // READY-NOTICE: shown to its creator as waiting for its `done`.
2087        if let Some(a) = &who {
2088            for t in &work.ready_for_done {
2089                let mut m = self.get(&t.id)?;
2090                let mut v = ready_seen_by(&m);
2091                if v.iter().any(|s| s == a) {
2092                    continue;
2093                }
2094                v.push(a.clone());
2095                m.metadata.insert(
2096                    crate::memory::MNEMO_META_READY_SEEN_BY.into(),
2097                    Value::Array(v.into_iter().map(Value::String).collect()),
2098                );
2099                self.put(m)?;
2100            }
2101        }
2102        for c in &work.lapsing {
2103            if let Some(mut m) = self.find_claim(&c.topic)? {
2104                m.metadata
2105                    .insert(MNEMO_META_WARNED_EXPIRY.into(), Value::from(c.expires_at));
2106                self.put(m)?;
2107            }
2108        }
2109        Ok(())
2110    }
2111
2112    /// 13a (13.1b): whether wake-ups are paused (the kill switch): who
2113    /// paused them and when.
2114    pub fn wake_paused(&mut self) -> Result<Option<(String, i64)>> {
2115        let Some(m) = self
2116            .about_in(crate::memory::VisibilitySet::ALL)?
2117            .into_iter()
2118            .find(is_manifest)
2119        else {
2120            return Ok(None);
2121        };
2122        Ok(m.metadata.get(MNEMO_META_WAKE_PAUSED).map(|v| {
2123            (
2124                v.get("by")
2125                    .and_then(Value::as_str)
2126                    .unwrap_or("")
2127                    .to_string(),
2128                v.get("at").and_then(Value::as_i64).unwrap_or(0),
2129            )
2130        }))
2131    }
2132
2133    /// 13a (13.1b): pause (`true`) or resume wake-ups for every session
2134    /// of this brain, on the manifest. Paused, nothing wakes anyone: items
2135    /// stay `sent`, and the per-turn hook and the brief still show them.
2136    pub fn set_wake_paused(&mut self, paused: bool) -> Result<WriteOutcome> {
2137        if self.read_only {
2138            return Err(MnemoError::ReadOnly);
2139        }
2140        let Some(mut m) = self
2141            .about_in(crate::memory::VisibilitySet::ALL)?
2142            .into_iter()
2143            .find(is_manifest)
2144        else {
2145            return Err(MnemoError::Invalid(
2146                "this brain has no manifest to record the pause on".into(),
2147            ));
2148        };
2149        if m.metadata.contains_key(MNEMO_META_WAKE_PAUSED) == paused {
2150            return Ok(WriteOutcome::Unchanged);
2151        }
2152        if paused {
2153            let mut v = Map::new();
2154            v.insert(
2155                "by".into(),
2156                Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
2157            );
2158            v.insert("at".into(), Value::from(self.coordination_now()));
2159            m.metadata
2160                .insert(MNEMO_META_WAKE_PAUSED.into(), Value::Object(v));
2161        } else {
2162            m.metadata.remove(MNEMO_META_WAKE_PAUSED);
2163        }
2164        self.put(m)?;
2165        Ok(WriteOutcome::Updated)
2166    }
2167
2168    /// 13a (13.1b): the wake-up guardrails, in the one place that marks an
2169    /// item `delivered`. For `agent` (and `role`), the items that may wake
2170    /// it: pre-approved tasks ready for its role, and messages addressed to
2171    /// it by id (never to its role or `all`), still `sent`. Then:
2172    /// - **paused** (the kill switch): [`Wake::Held`];
2173    /// - **an explicit reply past the hop cap** ([`crate::memory::HOP_CAP`])
2174    ///   or **a pair in a burst** ([`crate::memory::PAIR_BURST`] messages
2175    ///   either way in [`crate::memory::PAIR_BURST_SECS`]) wakes nobody;
2176    /// - **the recipient's rate** ([`crate::memory::WAKE_PER_HOUR`]) and
2177    ///   **cooldown** ([`crate::memory::WAKE_COOLDOWN_SECS`]), from its
2178    ///   presence record's `_mnemo.wakes`.
2179    ///
2180    /// On [`Wake::Now`] the items are marked `delivered` and the wake-up is
2181    /// recorded on the recipient's presence record, in place.
2182    pub fn wake(&mut self, agent: &str, role: Option<&str>) -> Result<Wake> {
2183        if self.read_only {
2184            return Err(MnemoError::ReadOnly);
2185        }
2186        let now = self.coordination_now();
2187        let sent = crate::memory::delivery::SENT;
2188        let mut tasks = Vec::new();
2189        for t in self.ready_tasks(role)? {
2190            let m = self.get(&t.id)?;
2191            if t.pre_approved
2192                && meta_string(&m, MNEMO_META_DELIVERY).as_deref() == Some(sent)
2193                && !seen_by(&m).iter().any(|s| s == agent)
2194            {
2195                tasks.push(t.id);
2196            }
2197        }
2198        let all_msgs: Vec<Message> = self
2199            .messages()?
2200            .iter()
2201            .filter_map(Message::from_memory)
2202            .collect();
2203        let candidates: Vec<&Message> = all_msgs
2204            .iter()
2205            .filter(|m| m.to == agent && m.from != agent)
2206            .filter(|m| m.status == crate::memory::MESSAGE_UNREAD && m.delivery == sent)
2207            .collect();
2208        if tasks.is_empty() && candidates.is_empty() {
2209            return Ok(Wake::Nothing);
2210        }
2211        if self.wake_paused()?.is_some() {
2212            return Ok(Wake::Held("paused"));
2213        }
2214        let burst = |a: &str, b: &str| {
2215            all_msgs
2216                .iter()
2217                .filter(|m| now - m.created_at <= PAIR_BURST_SECS)
2218                .filter(|m| (m.from == a && m.to == b) || (m.from == b && m.to == a))
2219                .count()
2220                >= PAIR_BURST
2221        };
2222        let mut reason = None;
2223        let messages: Vec<Ulid> = candidates
2224            .iter()
2225            .filter(|m| {
2226                let reply = m.conversation != m.id.to_string();
2227                if reply && m.hops > HOP_CAP {
2228                    reason = Some("the thread reached its hop cap");
2229                    return false;
2230                }
2231                if burst(&m.from, &m.to) {
2232                    reason = Some("a burst of messages between two agents");
2233                    return false;
2234                }
2235                true
2236            })
2237            .map(|m| m.id)
2238            .collect();
2239        if tasks.is_empty() && messages.is_empty() {
2240            return Ok(Wake::Held(reason.unwrap_or("a guardrail")));
2241        }
2242        // The recipient's rate and cooldown, from its presence record.
2243        let presence = self
2244            .coordination_records(MNEMO_META_KIND_PRESENCE, Some(agent))?
2245            .into_iter()
2246            .next();
2247        let mut wakes: Vec<i64> = presence
2248            .as_ref()
2249            .and_then(|m| m.metadata.get(MNEMO_META_WAKES))
2250            .and_then(Value::as_array)
2251            .map(|a| a.iter().filter_map(Value::as_i64).collect())
2252            .unwrap_or_default();
2253        wakes.retain(|t| now - t < 3600 && *t <= now);
2254        if wakes.len() >= WAKE_PER_HOUR {
2255            return Ok(Wake::Held("the hourly limit of wake-ups"));
2256        }
2257        if wakes.iter().any(|t| now - t < WAKE_COOLDOWN_SECS) {
2258            return Ok(Wake::Held("the cooldown between wake-ups"));
2259        }
2260        wakes.push(now);
2261        let delivered = Value::String(crate::memory::delivery::DELIVERED.into());
2262        for id in tasks.iter().chain(messages.iter()) {
2263            let mut m = self.get(id)?;
2264            m.metadata
2265                .insert(MNEMO_META_DELIVERY.into(), delivered.clone());
2266            self.put(m)?;
2267        }
2268        let w = Value::Array(wakes.into_iter().map(Value::from).collect());
2269        match presence {
2270            Some(mut m) => {
2271                m.metadata.insert(MNEMO_META_WAKES.into(), w);
2272                self.put(m)?;
2273            }
2274            None => {
2275                let mut meta = Map::new();
2276                meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.to_string()));
2277                meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(0));
2278                meta.insert(MNEMO_META_PRESENCE_LOCK.into(), Value::Bool(false));
2279                meta.insert(MNEMO_META_WAKES.into(), w);
2280                self.put_coordination_with_id(
2281                    Ulid::new(),
2282                    MNEMO_META_KIND_PRESENCE,
2283                    format!("presence {agent}"),
2284                    meta,
2285                )?;
2286            }
2287        }
2288        Ok(Wake::Now {
2289            tasks: tasks.len(),
2290            messages: messages.len(),
2291        })
2292    }
2293}
2294
2295// --- 13a step 7: freshness (13.6) --------------------------------------------
2296
2297/// 13a (13.6): one stale record ([`Mnemo::stale`]).
2298#[derive(Debug, Clone, PartialEq, Eq)]
2299#[non_exhaustive]
2300pub struct Stale {
2301    /// The record's id.
2302    pub id: Ulid,
2303    /// What it is: `essence state`, `essence next`, `essence open`, `task
2304    /// active`, `task blocked`, `message unread`, or `fact` (past its
2305    /// `review_by`).
2306    pub what: String,
2307    /// When it went stale, in unix seconds.
2308    pub since: i64,
2309    /// Its first line (a task's title, a message's subject).
2310    pub text: String,
2311    /// Whose it is: a task's owner, a message's recipient, else its author.
2312    pub whose: Option<String>,
2313    /// Its visibility level (`public`, `team` or `private`).
2314    pub visibility: String,
2315}
2316
2317impl Mnemo {
2318    /// 13a (13.6): every record that's stale now
2319    /// ([`crate::memory::stale_since`]), oldest first: past its `review_by`,
2320    /// or older than its kind's default (essence `state` and `next` 14
2321    /// days, `open` 30, an `active` task with no update 3, a `blocked` one
2322    /// 7, an unread message 3). Reads only the rows that can be (essence,
2323    /// coordination, and those with a `review_by`).
2324    pub fn stale(&mut self) -> Result<Vec<Stale>> {
2325        use super::records::{ROW_KIND_ESSENCE, ROW_REVIEW};
2326        let now = self.coordination_now();
2327        let entries: Vec<CatalogEntry> = self
2328            .catalog
2329            .iter()
2330            .filter(|e| !e.deleted)
2331            .filter(|e| {
2332                e.v9.is_none_or(|r| {
2333                    r.kind == ROW_KIND_ESSENCE
2334                        || r.kind == ROW_KIND_COORDINATION
2335                        || r.flags & ROW_REVIEW != 0
2336                })
2337            })
2338            .cloned()
2339            .collect();
2340        let mut out = Vec::new();
2341        for e in entries {
2342            let m = self.read_memory(&e)?;
2343            let Some(since) = crate::memory::stale_since(&m, now) else {
2344                continue;
2345            };
2346            let s = |k: &str| meta_string(&m, k);
2347            let kind = s(MNEMO_META_KIND);
2348            let what = match kind.as_deref() {
2349                Some("essence") => format!(
2350                    "essence {}",
2351                    s(crate::memory::MNEMO_META_SECTION).unwrap_or_default()
2352                ),
2353                Some(k @ ("task" | "message")) => {
2354                    format!("{k} {}", s(MNEMO_META_STATUS).unwrap_or_default())
2355                }
2356                Some(k) => k.to_string(),
2357                None => "fact".to_string(),
2358            };
2359            let whose = match kind.as_deref() {
2360                Some("task") => s(MNEMO_META_OWNER),
2361                Some("message") => s(MNEMO_META_TO),
2362                _ => s(crate::memory::MNEMO_META_AUTHOR),
2363            };
2364            out.push(Stale {
2365                id: m.id,
2366                what,
2367                since,
2368                text: m.content.lines().next().unwrap_or("").to_string(),
2369                whose,
2370                visibility: crate::memory::visibility_of(&m).to_string(),
2371            });
2372        }
2373        out.sort_by_key(|x| (x.since, x.id.0));
2374        Ok(out)
2375    }
2376}
2377
2378/// 13a (ABOUT-COUNT): the live records by what they are.
2379#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
2380#[non_exhaustive]
2381pub struct KindCounts {
2382    /// Facts and onboarding records (what recall and `about` read).
2383    pub facts: usize,
2384    /// Thread turns and thread links.
2385    pub turns: usize,
2386    /// Essence items.
2387    pub essence: usize,
2388    /// Messages, tasks, claims and presence records.
2389    pub coordination: usize,
2390}
2391
2392impl Mnemo {
2393    /// 13a (ABOUT-COUNT): how many live records of each kind, from the
2394    /// catalog's rows (a v8 file's records have none and count as facts).
2395    /// Superseded versions count too, as in [`Mnemo::len`].
2396    pub fn kind_counts(&self) -> KindCounts {
2397        use super::records::{ROW_KIND_ESSENCE, ROW_KIND_THREAD_LINK, ROW_KIND_TURN};
2398        let mut c = KindCounts::default();
2399        for e in self.catalog.iter().filter(|e| !e.deleted) {
2400            match e.v9.map(|r| r.kind) {
2401                Some(ROW_KIND_TURN | ROW_KIND_THREAD_LINK) => c.turns += 1,
2402                Some(ROW_KIND_ESSENCE) => c.essence += 1,
2403                Some(ROW_KIND_COORDINATION) => c.coordination += 1,
2404                _ => c.facts += 1,
2405            }
2406        }
2407        c
2408    }
2409}
2410
2411#[cfg(test)]
2412mod legacy_scan_tests {
2413    use super::is_sentinel;
2414
2415    /// COORD-LEGACY-SCAN: the sentinel, quantised as the column stores it,
2416    /// is recognised at every width; an ordinary vector isn't.
2417    #[test]
2418    fn the_sentinel_is_told_from_an_ordinary_vector() {
2419        for dims in [4, 32, 384, 768] {
2420            let s = vec![1.0 / (dims as f32).sqrt(); dims];
2421            let (h, _) = crate::veccol::quantize(&s);
2422            assert!(is_sentinel(&h), "{dims}");
2423            let mut v = s.clone();
2424            v[dims / 2] += 0.05;
2425            assert!(!is_sentinel(&crate::veccol::quantize(&v).0), "{dims}");
2426            let flat = vec![0.5; dims];
2427            assert_eq!(
2428                is_sentinel(&crate::veccol::quantize(&flat).0),
2429                dims == 4,
2430                "{dims}"
2431            );
2432        }
2433        assert!(!is_sentinel(&[]));
2434    }
2435}