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