1use super::*;
8
9impl Mnemo {
10 #[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 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#[derive(Debug, Clone, Default, PartialEq)]
54#[non_exhaustive]
55pub struct Message {
56 pub id: Ulid,
58 pub to: String,
60 pub from: String,
62 pub subject: String,
64 pub body: String,
66 pub refs: Vec<String>,
68 pub conversation: String,
70 pub hops: u64,
72 pub status: String,
74 pub delivery: String,
76 pub created_at: i64,
78 pub acked_at: Option<i64>,
80}
81
82impl Message {
83 pub fn from_memory(m: &Memory) -> Option<Message> {
85 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)
86 != Some(crate::memory::MNEMO_META_KIND_MESSAGE)
87 {
88 return None;
89 }
90 let s = |k: &str| {
91 m.metadata
92 .get(k)
93 .and_then(Value::as_str)
94 .unwrap_or("")
95 .to_string()
96 };
97 let (subject, body) = match m.content.split_once("\n\n") {
98 Some((a, b)) => (a.to_string(), b.to_string()),
99 None => (m.content.clone(), String::new()),
100 };
101 Some(Message {
102 id: m.id,
103 to: s(MNEMO_META_TO),
104 from: s(MNEMO_META_FROM),
105 subject,
106 body,
107 refs: m
108 .metadata
109 .get(MNEMO_META_REFS)
110 .and_then(Value::as_array)
111 .map(|a| {
112 a.iter()
113 .filter_map(|v| v.as_str().map(str::to_string))
114 .collect()
115 })
116 .unwrap_or_default(),
117 conversation: s(MNEMO_META_CONVERSATION),
118 hops: m
119 .metadata
120 .get(MNEMO_META_HOPS)
121 .and_then(Value::as_u64)
122 .unwrap_or(0),
123 status: s(MNEMO_META_STATUS),
124 delivery: s(MNEMO_META_DELIVERY),
125 created_at: m.created_at,
126 acked_at: m.metadata.get(MNEMO_META_ACKED_AT).and_then(Value::as_i64),
127 })
128 }
129
130 pub fn is_for(&self, agent: Option<&str>, role: Option<&str>) -> bool {
133 if agent.is_some_and(|a| a == self.from) {
134 return false;
135 }
136 self.to == "all"
137 || agent.is_some_and(|a| a == self.to)
138 || role.is_some_and(|r| self.to.strip_prefix("role:") == Some(r))
139 }
140}
141
142fn valid_address(to: &str) -> bool {
144 to == "all"
145 || crate::memory::valid_agent_id(to) && !to.starts_with("role:")
146 || to
147 .strip_prefix("role:")
148 .is_some_and(crate::memory::valid_agent_id)
149}
150
151fn seen_by(m: &Memory) -> Vec<String> {
154 m.metadata
155 .get(crate::memory::MNEMO_META_SEEN_BY)
156 .and_then(Value::as_array)
157 .map(|a| {
158 a.iter()
159 .filter_map(|v| v.as_str().map(str::to_string))
160 .collect()
161 })
162 .unwrap_or_default()
163}
164
165fn is_sentinel(h: &[u16]) -> bool {
168 let Some(&first) = h.first() else {
169 return false;
170 };
171 let want = 1.0 / (h.len() as f32).sqrt();
172 h.iter().all(|&x| x == first) && (crate::veccol::f16_to_f32(first) - want).abs() < 1e-3
173}
174
175fn ready_seen_by(m: &Memory) -> Vec<String> {
178 m.metadata
179 .get(crate::memory::MNEMO_META_READY_SEEN_BY)
180 .and_then(Value::as_array)
181 .map(|a| {
182 a.iter()
183 .filter_map(|v| v.as_str().map(str::to_string))
184 .collect()
185 })
186 .unwrap_or_default()
187}
188
189fn add_seen_by(m: &mut Memory, agent: &str) -> bool {
191 let mut v = seen_by(m);
192 if v.iter().any(|a| a == agent) {
193 return false;
194 }
195 v.push(agent.to_string());
196 m.metadata.insert(
197 crate::memory::MNEMO_META_SEEN_BY.into(),
198 Value::Array(v.into_iter().map(Value::String).collect()),
199 );
200 true
201}
202
203impl Mnemo {
204 pub(super) fn coordination_records(
208 &mut self,
209 kind: &str,
210 locator: Option<&str>,
211 ) -> Result<Vec<Memory>> {
212 let want = locator.map(|l| locator_hash_of(kind, l));
213 let legacy = self.legacy_coordination_ids()?;
214 let entries: Vec<CatalogEntry> = self
215 .catalog
216 .iter()
217 .filter(|e| !e.deleted)
218 .filter(|e| {
219 legacy.contains(&e.id)
220 || e.v9.is_none_or(|r| {
221 r.kind == ROW_KIND_COORDINATION && want.is_none_or(|h| r.thread_hash == h)
222 })
223 })
224 .cloned()
225 .collect();
226 let mut out = Vec::new();
227 for e in entries {
228 let m = self.read_memory(&e)?;
229 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(kind) {
230 continue;
231 }
232 if let Some(l) = locator {
233 if locator_of(&m) != Some(l) {
234 continue;
235 }
236 }
237 out.push(m);
238 }
239 Ok(out)
240 }
241
242 fn legacy_coordination_ids(&mut self) -> Result<std::collections::HashSet<u128>> {
250 if let Some(ids) = &self.legacy_coordination {
251 return Ok(ids.clone());
252 }
253 let episodic = super::records::memory_type_code(MemoryType::Episodic);
254 let candidates: Vec<CatalogEntry> = self
255 .catalog
256 .iter()
257 .filter(|e| !e.deleted)
258 .filter(|e| {
259 e.v9.is_some_and(|r| {
260 r.kind == super::records::ROW_KIND_FACT && r.memory_type == episodic
261 })
262 })
263 .cloned()
264 .collect();
265 let mut ids = std::collections::HashSet::new();
266 let mut pages: std::collections::HashMap<(u64, u64), Option<Vec<u8>>> =
268 std::collections::HashMap::new();
269 for e in candidates {
270 let vector = match e.v9 {
271 Some(r) if r.vec_page != 0 && !self.has_hot_vector(&e) => {
272 let page = pages
273 .entry((r.vec_page, r.vec_gen))
274 .or_insert_with(|| self.pager.read_page(r.vec_page, r.vec_gen).ok());
275 page.as_ref().and_then(|p| {
276 crate::veccol::decode_entry(p, self.dimensions, r.vec_slot as usize).ok()
277 })
278 }
279 _ => self.column_entry(&e).ok(),
280 };
281 if matches!(vector, Some((h, _)) if !is_sentinel(&h)) {
282 continue;
283 }
284 if is_coordination(&self.read_memory(&e)?) {
285 ids.insert(e.id);
286 }
287 }
288 self.legacy_coordination = Some(ids.clone());
289 Ok(ids)
290 }
291
292 pub fn mistagged_coordination(&mut self) -> Result<usize> {
296 let ids = self.legacy_coordination_ids()?;
297 Ok(self
298 .catalog
299 .iter()
300 .filter(|e| !e.deleted && ids.contains(&e.id))
301 .filter(|e| {
302 e.v9.is_some_and(|r| r.kind == super::records::ROW_KIND_FACT)
303 })
304 .count())
305 }
306
307 fn messages(&mut self) -> Result<Vec<Memory>> {
309 let mut out = self.coordination_records(crate::memory::MNEMO_META_KIND_MESSAGE, None)?;
310 out.sort_by_key(|m| m.created_at);
313 Ok(out)
314 }
315
316 #[allow(clippy::too_many_arguments)]
328 pub fn post(
329 &mut self,
330 to: &str,
331 subject: &str,
332 body: &str,
333 refs: &[String],
334 conversation: Option<&str>,
335 from: Option<&str>,
336 from_role: Option<&str>,
337 ) -> Result<Message> {
338 if self.read_only {
339 return Err(MnemoError::ReadOnly);
340 }
341 if !valid_address(to) {
342 return Err(MnemoError::Invalid(format!(
343 "{to:?} isn't an address: an agent id, role:<role>, or all"
344 )));
345 }
346 let subject = subject.trim();
347 if subject.is_empty() || subject.contains('\n') {
348 return Err(MnemoError::Invalid(
349 "a message's subject is one line, and not empty".into(),
350 ));
351 }
352 if subject.len() > crate::memory::MESSAGE_SUBJECT_MAX {
353 return Err(MnemoError::Invalid(format!(
354 "a message's subject is at most {} bytes",
355 crate::memory::MESSAGE_SUBJECT_MAX
356 )));
357 }
358 if body.len() > crate::memory::MESSAGE_BODY_MAX {
359 return Err(MnemoError::Invalid(format!(
360 "a message's body is at most {} bytes; put a longer one in a fact and send its id \
361 in refs",
362 crate::memory::MESSAGE_BODY_MAX
363 )));
364 }
365 let from = from
366 .map(str::to_string)
367 .or_else(|| self.author.clone())
368 .unwrap_or_else(|| "anonymous".to_string());
369 let now = memory::now_secs();
370 let earlier: Vec<Message> = self
371 .messages()?
372 .iter()
373 .filter_map(Message::from_memory)
374 .collect();
375 let mut hops = 0u64;
376 if let Some(c) = conversation {
377 if let Some(h) = earlier
378 .iter()
379 .filter(|m| m.conversation == c)
380 .map(|m| m.hops)
381 .max()
382 {
383 hops = h + 1;
384 }
385 }
386 if let Some(h) = earlier
389 .iter()
390 .filter(|m| now - m.created_at <= crate::memory::MESSAGE_PAIR_CARRY_SECS)
391 .filter(|m| (m.from == from && m.to == to) || (m.from == to && m.to == from))
392 .map(|m| m.hops)
393 .max()
394 {
395 hops = hops.max(h + 1);
396 }
397 let id = Ulid::new();
398 let conversation = conversation
399 .map(str::to_string)
400 .unwrap_or_else(|| id.to_string());
401 let mut meta = Map::new();
402 meta.insert(MNEMO_META_TO.into(), Value::String(to.into()));
403 meta.insert(MNEMO_META_FROM.into(), Value::String(from));
404 if let Some(r) = from_role {
405 meta.insert("_mnemo.from_role".into(), Value::String(r.to_string()));
406 }
407 meta.insert(MNEMO_META_CONVERSATION.into(), Value::String(conversation));
408 meta.insert(MNEMO_META_HOPS.into(), Value::from(hops));
409 meta.insert(
410 MNEMO_META_REFS.into(),
411 Value::Array(refs.iter().map(|r| Value::String(r.clone())).collect()),
412 );
413 meta.insert(
414 MNEMO_META_STATUS.into(),
415 Value::String(crate::memory::MESSAGE_UNREAD.into()),
416 );
417 meta.insert(
418 MNEMO_META_DELIVERY.into(),
419 Value::String(crate::memory::delivery::SENT.into()),
420 );
421 let content = if body.is_empty() {
422 subject.to_string()
423 } else {
424 format!("{subject}\n\n{body}")
425 };
426 let id = self.put_coordination_with_id(
427 id,
428 crate::memory::MNEMO_META_KIND_MESSAGE,
429 content,
430 meta,
431 )?;
432 let m = self.get(&id)?;
433 Ok(Message::from_memory(&m).expect("just written"))
434 }
435
436 pub fn inbox(
441 &mut self,
442 agent: Option<&str>,
443 role: Option<&str>,
444 unread_only: bool,
445 ) -> Result<Vec<Message>> {
446 self.inbox_in(
447 agent,
448 role,
449 unread_only,
450 crate::memory::VisibilitySet::DEFAULT,
451 )
452 }
453
454 pub fn inbox_in(
457 &mut self,
458 agent: Option<&str>,
459 role: Option<&str>,
460 unread_only: bool,
461 visibility: crate::memory::VisibilitySet,
462 ) -> Result<Vec<Message>> {
463 Ok(self
464 .messages()?
465 .iter()
466 .filter(|m| visibility.shows(m))
467 .filter_map(Message::from_memory)
468 .filter(|m| m.is_for(agent, role))
469 .filter(|m| !unread_only || m.status == crate::memory::MESSAGE_UNREAD)
470 .collect())
471 }
472
473 pub fn mark_seen(&mut self, ids: &[Ulid]) -> Result<usize> {
476 if self.read_only {
477 return Err(MnemoError::ReadOnly);
478 }
479 let mut changed = 0;
480 for id in ids {
481 let mut m = self.get(id)?;
482 let Some(msg) = Message::from_memory(&m) else {
483 continue;
484 };
485 let mut dirty = false;
486 if msg.delivery == crate::memory::delivery::SENT
487 || msg.delivery == crate::memory::delivery::DELIVERED
488 {
489 m.metadata.insert(
490 MNEMO_META_DELIVERY.into(),
491 Value::String(crate::memory::delivery::SEEN.into()),
492 );
493 dirty = true;
494 }
495 if msg.to == "all" || msg.to.starts_with("role:") {
498 if let Some(a) = self.author.clone() {
499 dirty |= add_seen_by(&mut m, &a);
500 }
501 }
502 if dirty {
503 self.put(m)?;
504 changed += 1;
505 }
506 }
507 Ok(changed)
508 }
509
510 pub fn ack(&mut self, id: &Ulid, note: Option<&str>, by: Option<&str>) -> Result<WriteOutcome> {
515 if self.read_only {
516 return Err(MnemoError::ReadOnly);
517 }
518 let mut m = self.get(id)?;
519 let Some(msg) = Message::from_memory(&m) else {
520 return Err(MnemoError::Invalid(format!("{id} isn't a message")));
521 };
522 if msg.status == crate::memory::MESSAGE_ACKED {
523 return Ok(WriteOutcome::Unchanged);
524 }
525 let now = memory::now_secs();
526 let by = by
527 .map(str::to_string)
528 .or_else(|| self.author.clone())
529 .unwrap_or_else(|| "anonymous".to_string());
530 let mut entry = Map::new();
531 entry.insert("from".into(), Value::String(msg.status.clone()));
532 entry.insert(
533 "to".into(),
534 Value::String(crate::memory::MESSAGE_ACKED.into()),
535 );
536 entry.insert("at".into(), Value::from(now));
537 entry.insert("by".into(), Value::String(by));
538 if let Some(n) = note {
539 entry.insert("note".into(), Value::String(n.to_string()));
540 }
541 let mut history = m
542 .metadata
543 .get(MNEMO_META_STATUS_HISTORY)
544 .and_then(Value::as_array)
545 .cloned()
546 .unwrap_or_default();
547 history.push(Value::Object(entry));
548 m.metadata
549 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(history));
550 m.metadata.insert(
551 MNEMO_META_STATUS.into(),
552 Value::String(crate::memory::MESSAGE_ACKED.into()),
553 );
554 m.metadata.insert(
555 MNEMO_META_DELIVERY.into(),
556 Value::String(crate::memory::delivery::DONE.into()),
557 );
558 m.metadata
559 .insert(MNEMO_META_ACKED_AT.into(), Value::from(now));
560 self.put(m)?;
561 Ok(WriteOutcome::Updated)
562 }
563
564 pub fn prune_messages(&mut self, older_than_secs: i64) -> Result<usize> {
568 if self.read_only {
569 return Err(MnemoError::ReadOnly);
570 }
571 let now = memory::now_secs();
572 let old: Vec<Ulid> = self
573 .messages()?
574 .iter()
575 .filter_map(Message::from_memory)
576 .filter(|m| prunable(m, now, older_than_secs))
577 .map(|m| m.id)
578 .collect();
579 for id in &old {
580 self.delete(id)?;
581 }
582 Ok(old.len())
583 }
584}
585
586fn prunable(m: &Message, now: i64, keep: i64) -> bool {
588 m.status == crate::memory::MESSAGE_ACKED && m.acked_at.is_some_and(|t| now - t > keep)
589}
590
591pub(super) fn compact_drops(m: &Memory, now: i64) -> bool {
594 Message::from_memory(m)
595 .is_some_and(|msg| prunable(&msg, now, crate::memory::MESSAGE_ACKED_KEEP_SECS))
596}
597
598use crate::memory::{
601 CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
602 MNEMO_META_AGENT, MNEMO_META_CLAIM_TOKEN, MNEMO_META_DEAD_SEEN_AT, MNEMO_META_EXPIRES_AT,
603 MNEMO_META_HOLDER, MNEMO_META_HOLDER_LOCK, MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_PRESENCE,
604 MNEMO_META_LAST_ACTIVE, MNEMO_META_LEASE, MNEMO_META_PRESENCE_LOCK, MNEMO_META_TOOL,
605 MNEMO_META_TOPIC, PRESENCE_EVERY_SECS,
606};
607
608fn locator_of(m: &Memory) -> Option<&str> {
610 let key = match m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)? {
611 MNEMO_META_KIND_CLAIM => MNEMO_META_TOPIC,
612 MNEMO_META_KIND_PRESENCE => MNEMO_META_AGENT,
613 crate::memory::MNEMO_META_KIND_TASK => crate::memory::MNEMO_META_SLUG,
614 crate::memory::MNEMO_META_KIND_FINDING => crate::memory::MNEMO_META_FINDING_ID,
615 _ => return None,
616 };
617 m.metadata.get(key).and_then(Value::as_str)
618}
619
620fn locator_hash_of(kind: &str, locator: &str) -> u32 {
621 super::records::fnv1a32(&[b"_mnemo.coordination", kind.as_bytes(), locator.as_bytes()])
622}
623
624pub(super) fn locator_hash(m: &Memory) -> u32 {
628 match (
629 m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str),
630 locator_of(m),
631 ) {
632 (Some(kind), Some(l)) => locator_hash_of(kind, l),
633 _ => 0,
634 }
635}
636
637#[derive(Debug, Clone, PartialEq, Eq)]
639pub enum ClaimOutcome {
640 Claimed {
643 token: String,
645 expires_at: i64,
647 },
648 HeldBy {
650 agent: String,
652 expires_at: i64,
654 },
655}
656
657#[derive(Debug, Clone, Copy, PartialEq, Eq)]
659pub enum ClaimStatus {
660 Held {
662 expires_at: i64,
664 },
665 Released,
667 Lost,
671}
672
673#[derive(Debug, Clone, Default, PartialEq, Eq)]
675#[non_exhaustive]
676pub struct Claim {
677 pub topic: String,
679 pub holder: String,
681 pub expires_at: i64,
683 pub lease: i64,
685}
686
687#[derive(Debug, Clone, Copy, PartialEq, Eq)]
689pub enum Alive {
690 Yes,
692 No,
694 Unknown,
697}
698
699#[derive(Debug, Clone, PartialEq, Eq)]
701#[non_exhaustive]
702pub struct Presence {
703 pub agent: String,
705 pub role: Option<String>,
707 pub tool: Option<String>,
709 pub last_active: i64,
711 pub alive: Alive,
713 pub claims: Vec<String>,
715}
716
717fn meta_i64(m: &Memory, k: &str) -> Option<i64> {
718 m.metadata.get(k).and_then(Value::as_i64)
719}
720
721fn meta_string(m: &Memory, k: &str) -> Option<String> {
722 m.metadata
723 .get(k)
724 .and_then(Value::as_str)
725 .map(str::to_string)
726}
727
728fn effective_expiry(m: &Memory, now: i64) -> Option<i64> {
731 let token = m
732 .metadata
733 .get(MNEMO_META_CLAIM_TOKEN)
734 .and_then(Value::as_str)?;
735 if token.is_empty() {
736 return None;
737 }
738 let expires = meta_i64(m, MNEMO_META_EXPIRES_AT)?;
739 let lease = meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT);
740 Some(expires.min(now.saturating_add(lease)))
741}
742
743fn is_live(m: &Memory, now: i64) -> bool {
745 effective_expiry(m, now).is_some_and(|e| now < e)
746}
747
748fn new_token() -> String {
749 format!(
750 "{:016x}{:016x}",
751 crate::crypto::random_u64(),
752 crate::crypto::random_u64()
753 )
754}
755
756fn check_topic(topic: &str) -> Result<()> {
757 if topic.trim().is_empty() || topic.contains('\n') || topic.len() > CLAIM_TOPIC_MAX {
758 return Err(MnemoError::Invalid(format!(
759 "a claim's topic is one line, not empty, at most {CLAIM_TOPIC_MAX} bytes"
760 )));
761 }
762 Ok(())
763}
764
765fn check_ttl(ttl: Option<i64>) -> Result<i64> {
766 let t = ttl.unwrap_or(CLAIM_TTL_DEFAULT);
767 if !(CLAIM_TTL_MIN..=CLAIM_TTL_MAX).contains(&t) {
768 return Err(MnemoError::Invalid(format!(
769 "a claim's ttl is {CLAIM_TTL_MIN} s to {CLAIM_TTL_MAX} s (24 h); got {t}"
770 )));
771 }
772 Ok(t)
773}
774
775impl Mnemo {
776 pub fn coordination_now(&self) -> i64 {
779 #[cfg(feature = "dev-hooks")]
780 let env: i64 = std::env::var("MNEMO_DEV_CLOCK_OFFSET")
781 .ok()
782 .and_then(|v| v.parse().ok())
783 .unwrap_or(0);
784 #[cfg(not(feature = "dev-hooks"))]
785 let env: i64 = 0;
786 memory::now_secs() + self.clock_offset + env
787 }
788
789 #[cfg(feature = "dev-hooks")]
792 #[doc(hidden)]
793 pub fn __set_clock_offset_for_testing(&mut self, secs: i64) {
794 self.clock_offset = secs;
795 }
796
797 fn claim_agent(&self) -> Result<String> {
798 self.author.clone().ok_or_else(|| {
799 MnemoError::Invalid(
800 "a claim needs an agent: set MNEMO_AGENT (or --as), or call set_author".into(),
801 )
802 })
803 }
804
805 fn find_claim(&mut self, topic: &str) -> Result<Option<Memory>> {
806 Ok(self
807 .coordination_records(MNEMO_META_KIND_CLAIM, Some(topic))?
808 .into_iter()
809 .next())
810 }
811
812 pub fn claim(&mut self, topic: &str, ttl: Option<i64>) -> Result<ClaimOutcome> {
827 if self.read_only {
828 return Err(MnemoError::ReadOnly);
829 }
830 check_topic(topic)?;
831 let ttl = check_ttl(ttl)?;
832 let agent = self.claim_agent()?;
833 let now = self.coordination_now();
834 let existing = self.find_claim(topic)?;
835 if let Some(mut m) = existing.clone() {
836 if is_live(&m, now) {
837 let holder = meta_string(&m, MNEMO_META_HOLDER).unwrap_or_default();
838 let expires = effective_expiry(&m, now).unwrap_or(now);
839 let mut changed = false;
840 let mut lapse = false;
841 let had_lock = m
842 .metadata
843 .get(MNEMO_META_HOLDER_LOCK)
844 .and_then(Value::as_bool)
845 .unwrap_or(false);
846 if had_lock && holder != agent {
847 match crate::shared::probe_presence_once(&self.path, &holder) {
848 Some(false) => match meta_i64(&m, MNEMO_META_DEAD_SEEN_AT) {
849 Some(t) if now - t >= CLAIM_LAPSE_GRACE_SECS => lapse = true,
850 Some(_) => {}
851 None => {
852 m.metadata
853 .insert(MNEMO_META_DEAD_SEEN_AT.into(), Value::from(now));
854 changed = true;
855 }
856 },
857 _ => {
858 changed |= m.metadata.remove(MNEMO_META_DEAD_SEEN_AT).is_some();
859 }
860 }
861 }
862 if !lapse {
863 if meta_i64(&m, MNEMO_META_EXPIRES_AT) != Some(expires) {
866 m.metadata
867 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires));
868 changed = true;
869 }
870 if changed {
871 self.put(m)?;
872 }
873 return Ok(ClaimOutcome::HeldBy {
874 agent: holder,
875 expires_at: expires,
876 });
877 }
878 }
879 }
880 let token = new_token();
881 let expires_at = now + ttl;
882 let mut meta = existing
883 .as_ref()
884 .map(|m| m.metadata.clone())
885 .unwrap_or_default();
886 meta.remove(MNEMO_META_DEAD_SEEN_AT);
887 meta.insert(MNEMO_META_TOPIC.into(), Value::String(topic.to_string()));
888 meta.insert(MNEMO_META_HOLDER.into(), Value::String(agent));
889 meta.insert(MNEMO_META_CLAIM_TOKEN.into(), Value::String(token.clone()));
890 meta.insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
891 meta.insert(MNEMO_META_LEASE.into(), Value::from(ttl));
892 meta.insert(
893 MNEMO_META_HOLDER_LOCK.into(),
894 Value::Bool(self.presence_held),
895 );
896 match existing {
897 Some(mut m) => {
898 m.metadata = meta;
899 self.put(m)?;
900 }
901 None => {
902 self.put_coordination_with_id(
903 Ulid::new(),
904 MNEMO_META_KIND_CLAIM,
905 format!("claim {topic}"),
906 meta,
907 )?;
908 }
909 }
910 Ok(ClaimOutcome::Claimed { token, expires_at })
911 }
912
913 pub fn renew(&mut self, topic: &str, token: &str, ttl: Option<i64>) -> Result<ClaimStatus> {
916 if self.read_only {
917 return Err(MnemoError::ReadOnly);
918 }
919 let now = self.coordination_now();
920 let Some(mut m) = self.find_claim(topic)? else {
921 return Ok(ClaimStatus::Lost);
922 };
923 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
924 return Ok(ClaimStatus::Lost);
925 }
926 let lease = match ttl {
927 Some(t) => check_ttl(Some(t))?,
928 None => meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
929 };
930 let expires_at = now + lease;
931 m.metadata
932 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
933 m.metadata
934 .insert(MNEMO_META_LEASE.into(), Value::from(lease));
935 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
936 self.put(m)?;
937 Ok(ClaimStatus::Held { expires_at })
938 }
939
940 pub fn release(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
943 if self.read_only {
944 return Err(MnemoError::ReadOnly);
945 }
946 let now = self.coordination_now();
947 let Some(mut m) = self.find_claim(topic)? else {
948 return Ok(ClaimStatus::Lost);
949 };
950 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
951 return Ok(ClaimStatus::Lost);
952 }
953 m.metadata.remove(MNEMO_META_CLAIM_TOKEN);
954 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
955 m.metadata
956 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
957 self.put(m)?;
958 Ok(ClaimStatus::Released)
959 }
960
961 pub fn check_claim(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
964 let now = self.coordination_now();
965 let Some(m) = self.find_claim(topic)? else {
966 return Ok(ClaimStatus::Lost);
967 };
968 if meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
969 return Ok(ClaimStatus::Lost);
970 }
971 match effective_expiry(&m, now) {
972 Some(e) if now < e => Ok(ClaimStatus::Held { expires_at: e }),
973 _ => Ok(ClaimStatus::Lost),
974 }
975 }
976
977 pub fn claims(&mut self) -> Result<Vec<Claim>> {
979 let now = self.coordination_now();
980 let mut out: Vec<Claim> = self
981 .coordination_records(MNEMO_META_KIND_CLAIM, None)?
982 .iter()
983 .filter(|m| is_live(m, now))
984 .map(|m| Claim {
985 topic: meta_string(m, MNEMO_META_TOPIC).unwrap_or_default(),
986 holder: meta_string(m, MNEMO_META_HOLDER).unwrap_or_default(),
987 expires_at: effective_expiry(m, now).unwrap_or(now),
988 lease: meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
989 })
990 .collect();
991 out.sort_by(|a, b| a.topic.cmp(&b.topic));
992 Ok(out)
993 }
994
995 pub fn touch_presence(&mut self, role: Option<&str>, tool: Option<&str>) -> Result<bool> {
1002 if self.read_only {
1003 return Err(MnemoError::ReadOnly);
1004 }
1005 let Some(agent) = self.author.clone() else {
1006 return Ok(false);
1007 };
1008 let now = self.coordination_now();
1009 let existing = self
1010 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(&agent))?
1011 .into_iter()
1012 .next();
1013 let role_v = role.map(|r| Value::String(r.to_string()));
1014 let tool_v = tool.map(|t| Value::String(t.to_string()));
1015 let defer = !self.presence_held
1019 && existing.as_ref().is_some_and(|m| {
1020 m.metadata
1021 .get(MNEMO_META_PRESENCE_LOCK)
1022 .and_then(Value::as_bool)
1023 .unwrap_or(false)
1024 });
1025 if let Some(m) = &existing {
1026 let fresh = meta_i64(m, MNEMO_META_LAST_ACTIVE)
1027 .is_some_and(|t| now >= t && now - t < PRESENCE_EVERY_SECS);
1028 let same = defer
1029 || (m.metadata.get(crate::memory::MNEMO_META_ROLE) == role_v.as_ref()
1030 && m.metadata.get(MNEMO_META_TOOL) == tool_v.as_ref()
1031 && m.metadata
1032 .get(MNEMO_META_PRESENCE_LOCK)
1033 .and_then(Value::as_bool)
1034 == Some(self.presence_held));
1035 if fresh && same {
1036 return Ok(false);
1037 }
1038 }
1039 if defer {
1040 let mut m = existing.expect("checked");
1041 m.metadata
1042 .insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1043 self.put(m)?;
1044 return Ok(true);
1045 }
1046 let mut meta = existing
1047 .as_ref()
1048 .map(|m| m.metadata.clone())
1049 .unwrap_or_default();
1050 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.clone()));
1051 for (k, v) in [
1052 (crate::memory::MNEMO_META_ROLE, role_v),
1053 (MNEMO_META_TOOL, tool_v),
1054 ] {
1055 match v {
1056 Some(v) => {
1057 meta.insert(k.into(), v);
1058 }
1059 None => {
1060 meta.remove(k);
1061 }
1062 }
1063 }
1064 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1065 meta.insert(
1066 MNEMO_META_PRESENCE_LOCK.into(),
1067 Value::Bool(self.presence_held),
1068 );
1069 match existing {
1070 Some(mut m) => {
1071 m.metadata = meta;
1072 self.put(m)?;
1073 }
1074 None => {
1075 self.put_coordination_with_id(
1076 Ulid::new(),
1077 MNEMO_META_KIND_PRESENCE,
1078 format!("presence {agent}"),
1079 meta,
1080 )?;
1081 }
1082 }
1083 Ok(true)
1084 }
1085
1086 pub fn who(&mut self) -> Result<Vec<Presence>> {
1091 let claims = self.claims()?;
1092 let records = self.coordination_records(MNEMO_META_KIND_PRESENCE, None)?;
1093 let mut out: Vec<Presence> = records
1094 .iter()
1095 .map(|m| {
1096 let agent = meta_string(m, MNEMO_META_AGENT).unwrap_or_default();
1097 let locked = m
1098 .metadata
1099 .get(MNEMO_META_PRESENCE_LOCK)
1100 .and_then(Value::as_bool)
1101 .unwrap_or(false);
1102 let alive = if !locked {
1103 Alive::Unknown
1104 } else {
1105 match crate::shared::probe_presence(&self.path, &agent) {
1106 Some(true) => Alive::Yes,
1107 Some(false) => Alive::No,
1108 None => Alive::Unknown,
1109 }
1110 };
1111 Presence {
1112 claims: claims
1113 .iter()
1114 .filter(|c| c.holder == agent)
1115 .map(|c| c.topic.clone())
1116 .collect(),
1117 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1118 tool: meta_string(m, MNEMO_META_TOOL),
1119 last_active: meta_i64(m, MNEMO_META_LAST_ACTIVE).unwrap_or(0),
1120 alive,
1121 agent,
1122 }
1123 })
1124 .collect();
1125 out.sort_by(|a, b| {
1126 b.last_active
1127 .cmp(&a.last_active)
1128 .then(a.agent.cmp(&b.agent))
1129 });
1130 Ok(out)
1131 }
1132}
1133
1134use crate::memory::{
1137 task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_KIND_TASK, MNEMO_META_OWNER,
1138 MNEMO_META_PRE_APPROVED, MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_SLUG_MAX, TASK_TRANSITIONS,
1139};
1140
1141#[derive(Debug, Clone, Default, PartialEq, Eq)]
1143#[non_exhaustive]
1144pub struct TaskSpec {
1145 pub title: String,
1147 pub body: String,
1149 pub role: Option<String>,
1151 pub after: Vec<String>,
1153 pub pre_approved: bool,
1155 pub slug: Option<String>,
1157 pub refs: Vec<String>,
1160}
1161
1162impl TaskSpec {
1163 pub fn new(title: impl Into<String>) -> Self {
1167 TaskSpec {
1168 title: title.into(),
1169 ..Default::default()
1170 }
1171 }
1172}
1173
1174const TASK_REFS_MAX: usize = 32;
1176const TASK_REF_MAX: usize = 200;
1177
1178#[derive(Debug, Clone, PartialEq)]
1180#[non_exhaustive]
1181pub struct Task {
1182 pub id: Ulid,
1184 pub slug: String,
1186 pub title: String,
1188 pub body: String,
1190 pub role: Option<String>,
1192 pub status: String,
1194 pub owner: Option<String>,
1196 pub creator: String,
1198 pub after: Vec<String>,
1200 pub pre_approved: bool,
1202 pub refs: Vec<String>,
1204 pub created_at: i64,
1206 pub history: Vec<Value>,
1209}
1210
1211impl Task {
1212 pub fn from_memory(m: &Memory) -> Option<Task> {
1214 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(MNEMO_META_KIND_TASK) {
1215 return None;
1216 }
1217 let (title, body) = match m.content.split_once("\n\n") {
1218 Some((a, b)) => (a.to_string(), b.to_string()),
1219 None => (m.content.clone(), String::new()),
1220 };
1221 Some(Task {
1222 id: m.id,
1223 slug: meta_string(m, MNEMO_META_SLUG).unwrap_or_default(),
1224 title,
1225 body,
1226 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1227 status: meta_string(m, MNEMO_META_STATUS).unwrap_or_default(),
1228 owner: meta_string(m, MNEMO_META_OWNER),
1229 creator: meta_string(m, MNEMO_META_CREATOR).unwrap_or_default(),
1230 after: m
1231 .metadata
1232 .get(MNEMO_META_AFTER)
1233 .and_then(Value::as_array)
1234 .map(|a| {
1235 a.iter()
1236 .filter_map(|v| v.as_str().map(str::to_string))
1237 .collect()
1238 })
1239 .unwrap_or_default(),
1240 pre_approved: m
1241 .metadata
1242 .get(MNEMO_META_PRE_APPROVED)
1243 .and_then(Value::as_bool)
1244 .unwrap_or(false),
1245 refs: m
1246 .metadata
1247 .get(crate::memory::MNEMO_META_REFS)
1248 .and_then(Value::as_array)
1249 .map(|a| {
1250 a.iter()
1251 .filter_map(|v| v.as_str().map(str::to_string))
1252 .collect()
1253 })
1254 .unwrap_or_default(),
1255 created_at: m.created_at,
1256 history: m
1257 .metadata
1258 .get(MNEMO_META_STATUS_HISTORY)
1259 .and_then(Value::as_array)
1260 .cloned()
1261 .unwrap_or_default(),
1262 })
1263 }
1264
1265 fn for_role(&self, role: Option<&str>) -> bool {
1268 self.role.is_none() || self.role.as_deref() == role
1269 }
1270}
1271
1272#[derive(Debug, Clone, PartialEq)]
1274#[non_exhaustive]
1275pub struct TaskTaken {
1276 pub task: Task,
1278 pub token: String,
1281 pub expires_at: i64,
1283 pub reclaimed_from: Option<String>,
1285}
1286
1287#[derive(Debug, Clone, PartialEq, Eq)]
1290#[non_exhaustive]
1291pub struct TaskClaim {
1292 pub token: String,
1294 pub expires_at: i64,
1296 pub retaken: bool,
1299}
1300
1301#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1303pub enum TaskLost {
1304 TakenBack,
1306 OtherToken,
1309}
1310
1311#[derive(Debug, Clone, PartialEq)]
1313pub enum TaskOutcome {
1314 Updated(Box<Task>, Option<TaskClaim>),
1318 Lost(TaskLost),
1320}
1321
1322pub fn slug_of(title: &str) -> String {
1325 let mut out = String::new();
1326 for c in title.chars() {
1327 if c.is_ascii_alphanumeric() {
1328 out.push(c.to_ascii_lowercase());
1329 } else if !out.ends_with('-') && !out.is_empty() {
1330 out.push('-');
1331 }
1332 if out.len() >= TASK_SLUG_MAX {
1333 break;
1334 }
1335 }
1336 out.trim_end_matches('-').to_string()
1337}
1338
1339fn valid_slug(s: &str) -> bool {
1340 !s.is_empty()
1341 && s.len() <= TASK_SLUG_MAX
1342 && s.bytes()
1343 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
1344}
1345
1346fn task_topic(slug: &str) -> String {
1347 format!("task:{slug}")
1348}
1349
1350impl Mnemo {
1351 fn task_records(&mut self, slug: Option<&str>) -> Result<Vec<Memory>> {
1352 let mut v = self.coordination_records(MNEMO_META_KIND_TASK, slug)?;
1353 v.sort_by_key(|m| m.created_at);
1354 Ok(v)
1355 }
1356
1357 fn task_record(&mut self, slug: &str) -> Result<Option<Memory>> {
1358 Ok(self.task_records(Some(slug))?.into_iter().next())
1359 }
1360
1361 pub fn task(&mut self, slug: &str) -> Result<Option<Task>> {
1363 Ok(self.task_record(slug)?.as_ref().and_then(Task::from_memory))
1364 }
1365
1366 pub fn tasks(&mut self, status: Option<&str>, role: Option<&str>) -> Result<Vec<Task>> {
1369 Ok(self
1370 .task_records(None)?
1371 .iter()
1372 .filter_map(Task::from_memory)
1373 .filter(|t| status.is_none_or(|s| t.status == s))
1374 .filter(|t| role.is_none() || t.for_role(role))
1375 .collect())
1376 }
1377
1378 pub fn ready_tasks(&mut self, role: Option<&str>) -> Result<Vec<Task>> {
1381 let all: Vec<Task> = self
1382 .task_records(None)?
1383 .iter()
1384 .filter_map(Task::from_memory)
1385 .collect();
1386 let done: std::collections::HashSet<&str> = all
1387 .iter()
1388 .filter(|t| t.status == task_status::DONE)
1389 .map(|t| t.slug.as_str())
1390 .collect();
1391 Ok(all
1392 .iter()
1393 .filter(|t| t.status == task_status::QUEUED && t.for_role(role))
1394 .filter(|t| t.after.iter().all(|a| done.contains(a.as_str())))
1395 .cloned()
1396 .collect())
1397 }
1398
1399 pub fn task_add(&mut self, spec: &TaskSpec) -> Result<(Task, WriteOutcome)> {
1405 if self.read_only {
1406 return Err(MnemoError::ReadOnly);
1407 }
1408 let title = spec.title.trim();
1409 if title.is_empty()
1410 || title.contains('\n')
1411 || title.len() > crate::memory::MESSAGE_SUBJECT_MAX
1412 {
1413 return Err(MnemoError::Invalid(format!(
1414 "a task's title is one line, not empty, at most {} bytes",
1415 crate::memory::MESSAGE_SUBJECT_MAX
1416 )));
1417 }
1418 if spec.body.len() > crate::memory::MESSAGE_BODY_MAX {
1419 return Err(MnemoError::Invalid(format!(
1420 "a task's body is at most {} bytes; put more in a fact and name it",
1421 crate::memory::MESSAGE_BODY_MAX
1422 )));
1423 }
1424 let slug = match &spec.slug {
1425 Some(s) => s.clone(),
1426 None => slug_of(title),
1427 };
1428 if !valid_slug(&slug) {
1429 return Err(MnemoError::Invalid(format!(
1430 "{slug:?} isn't a slug: 1 to {TASK_SLUG_MAX} of a-z, 0-9, '.', '_' and '-' \
1431 (give one with --slug)"
1432 )));
1433 }
1434 if let Some(r) = &spec.role {
1435 if !crate::memory::valid_agent_id(r) {
1436 return Err(MnemoError::Invalid(format!("{r:?} isn't a role")));
1437 }
1438 }
1439 if spec.refs.len() > TASK_REFS_MAX
1440 || spec
1441 .refs
1442 .iter()
1443 .any(|r| r.trim().is_empty() || r.contains('\n') || r.len() > TASK_REF_MAX)
1444 {
1445 return Err(MnemoError::Invalid(format!(
1446 "a task's refs: at most {TASK_REFS_MAX}, each one line, not empty, at most \
1447 {TASK_REF_MAX} bytes"
1448 )));
1449 }
1450 for a in &spec.after {
1451 if a == &slug {
1452 return Err(MnemoError::Invalid("a task can't wait for itself".into()));
1453 }
1454 if self.task_record(a)?.is_none() {
1455 return Err(MnemoError::Invalid(format!("after: no task {a:?}")));
1456 }
1457 }
1458 let content = if spec.body.is_empty() {
1459 title.to_string()
1460 } else {
1461 format!("{title}\n\n{}", spec.body)
1462 };
1463 let set = |meta: &mut Map<String, Value>| {
1464 match &spec.role {
1465 Some(r) => {
1466 meta.insert(
1467 crate::memory::MNEMO_META_ROLE.into(),
1468 Value::String(r.clone()),
1469 );
1470 }
1471 None => {
1472 meta.remove(crate::memory::MNEMO_META_ROLE);
1473 }
1474 }
1475 meta.insert(
1476 MNEMO_META_AFTER.into(),
1477 Value::Array(
1478 spec.after
1479 .iter()
1480 .map(|a| Value::String(a.clone()))
1481 .collect(),
1482 ),
1483 );
1484 meta.insert(
1485 MNEMO_META_PRE_APPROVED.into(),
1486 Value::Bool(spec.pre_approved),
1487 );
1488 if spec.refs.is_empty() {
1491 meta.remove(crate::memory::MNEMO_META_REFS);
1492 } else {
1493 meta.insert(
1494 crate::memory::MNEMO_META_REFS.into(),
1495 Value::Array(
1496 spec.refs
1497 .iter()
1498 .map(|r| Value::String(r.trim().to_string()))
1499 .collect(),
1500 ),
1501 );
1502 }
1503 };
1504 if let Some(mut m) = self.task_record(&slug)? {
1505 let t = Task::from_memory(&m).expect("a task");
1506 let mut meta = m.metadata.clone();
1507 set(&mut meta);
1508 if meta == m.metadata && m.content == content {
1509 return Ok((t, WriteOutcome::Unchanged));
1510 }
1511 if t.status == task_status::DONE {
1514 let mut n = 2;
1515 while self.task_record(&format!("{slug}-{n}"))?.is_some() {
1516 n += 1;
1517 }
1518 return Err(MnemoError::Invalid(format!(
1519 "{slug} is done; give a new slug ({slug}-{n}?)"
1520 )));
1521 }
1522 let caller = self.author.clone().unwrap_or_else(|| "anonymous".into());
1523 if caller != t.creator {
1524 return Err(MnemoError::Invalid(format!(
1525 "that slug is {}'s task; it wasn't changed",
1526 t.creator
1527 )));
1528 }
1529 if self.closes_cycle(&slug, &spec.after)? {
1531 return Err(MnemoError::Invalid(format!(
1532 "after: that would make {slug} wait for itself, through the tasks it waits for"
1533 )));
1534 }
1535 m.metadata = meta;
1536 m.content = content;
1537 let id = m.id;
1538 self.put(m)?;
1539 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1540 return Ok((t, WriteOutcome::Updated));
1541 }
1542 let mut meta = Map::new();
1543 meta.insert(MNEMO_META_SLUG.into(), Value::String(slug));
1544 meta.insert(
1545 MNEMO_META_STATUS.into(),
1546 Value::String(task_status::QUEUED.into()),
1547 );
1548 meta.insert(
1549 MNEMO_META_CREATOR.into(),
1550 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
1551 );
1552 meta.insert(
1553 MNEMO_META_DELIVERY.into(),
1554 Value::String(crate::memory::delivery::SENT.into()),
1555 );
1556 set(&mut meta);
1557 let id = self.put_coordination_with_id(Ulid::new(), MNEMO_META_KIND_TASK, content, meta)?;
1558 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1559 Ok((t, WriteOutcome::Added))
1560 }
1561
1562 fn closes_cycle(&mut self, slug: &str, after: &[String]) -> Result<bool> {
1565 let all: std::collections::HashMap<String, Vec<String>> = self
1566 .task_records(None)?
1567 .iter()
1568 .filter_map(Task::from_memory)
1569 .map(|t| (t.slug, t.after))
1570 .collect();
1571 let mut stack: Vec<&str> = after.iter().map(String::as_str).collect();
1572 let mut seen = std::collections::HashSet::new();
1573 while let Some(s) = stack.pop() {
1574 if s == slug {
1575 return Ok(true);
1576 }
1577 if seen.insert(s.to_string()) {
1578 if let Some(next) = all.get(s) {
1579 stack.extend(next.iter().map(String::as_str));
1580 }
1581 }
1582 }
1583 Ok(false)
1584 }
1585
1586 pub(super) fn task_history(
1588 m: &mut Memory,
1589 from: &str,
1590 to: &str,
1591 by: &str,
1592 at: i64,
1593 extra: &[(&str, &str)],
1594 ) {
1595 let mut e = Map::new();
1596 e.insert("from".into(), Value::String(from.into()));
1597 e.insert("to".into(), Value::String(to.into()));
1598 e.insert("at".into(), Value::from(at));
1599 e.insert("by".into(), Value::String(by.into()));
1600 for (k, v) in extra {
1601 e.insert((*k).into(), Value::String((*v).into()));
1602 }
1603 let mut h = m
1604 .metadata
1605 .get(MNEMO_META_STATUS_HISTORY)
1606 .and_then(Value::as_array)
1607 .cloned()
1608 .unwrap_or_default();
1609 h.push(Value::Object(e));
1610 m.metadata
1611 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(h));
1612 }
1613
1614 pub fn task_next(&mut self, role: Option<&str>) -> Result<Option<TaskTaken>> {
1622 if self.read_only {
1623 return Err(MnemoError::ReadOnly);
1624 }
1625 let agent = self.claim_agent()?;
1626 let now = self.coordination_now();
1627 let ready: Vec<Ulid> = self.ready_tasks(role)?.iter().map(|t| t.id).collect();
1628 let taken: Vec<Task> = self
1633 .task_records(None)?
1634 .iter()
1635 .filter_map(Task::from_memory)
1636 .filter(|t| t.status == task_status::ACTIVE || t.status == task_status::BLOCKED)
1637 .filter(|t| t.for_role(role))
1638 .collect();
1639 let (own, others): (Vec<&Task>, Vec<&Task>) = taken
1640 .iter()
1641 .partition(|t| t.owner.as_deref() == Some(agent.as_str()));
1642 for (id, back) in own
1643 .iter()
1644 .map(|t| (t.id, true))
1645 .chain(ready.into_iter().map(|i| (i, false)))
1646 .chain(others.iter().map(|t| (t.id, true)))
1647 {
1648 let mut m = self.get(&id)?;
1649 let t = Task::from_memory(&m).expect("a task");
1650 let (token, expires_at) =
1651 match self.claim(&task_topic(&t.slug), Some(TASK_CLAIM_TTL))? {
1652 ClaimOutcome::Claimed { token, expires_at } => (token, expires_at),
1653 ClaimOutcome::HeldBy { .. } => continue,
1654 };
1655 m = self.get(&id)?;
1658 let old = t.owner.clone();
1659 let own = old.as_deref() == Some(agent.as_str());
1660 if back && own {
1661 Self::task_history(
1662 &mut m,
1663 &t.status,
1664 task_status::ACTIVE,
1665 &agent,
1666 now,
1667 &[("note", "taken again after its claim lapsed")],
1668 );
1669 } else if back {
1670 let from = old.clone().unwrap_or_default();
1671 Self::task_history(
1672 &mut m,
1673 &t.status,
1674 task_status::ACTIVE,
1675 &agent,
1676 now,
1677 &[("reclaimed_from", from.as_str())],
1678 );
1679 } else {
1680 Self::task_history(
1681 &mut m,
1682 task_status::QUEUED,
1683 task_status::ACTIVE,
1684 &agent,
1685 now,
1686 &[],
1687 );
1688 }
1689 m.metadata.insert(
1690 MNEMO_META_STATUS.into(),
1691 Value::String(task_status::ACTIVE.into()),
1692 );
1693 m.metadata
1694 .insert(MNEMO_META_OWNER.into(), Value::String(agent.clone()));
1695 self.put(m)?;
1696 let task = Task::from_memory(&self.get(&id)?).expect("a task");
1697 return Ok(Some(TaskTaken {
1698 task,
1699 token,
1700 expires_at,
1701 reclaimed_from: if back && !own { old } else { None },
1702 }));
1703 }
1704 Ok(None)
1705 }
1706
1707 pub fn task_update(
1722 &mut self,
1723 slug: &str,
1724 status: Option<&str>,
1725 note: Option<&str>,
1726 token: Option<&str>,
1727 ) -> Result<TaskOutcome> {
1728 if self.read_only {
1729 return Err(MnemoError::ReadOnly);
1730 }
1731 let agent = self.claim_agent()?;
1732 let now = self.coordination_now();
1733 let Some(m) = self.task_record(slug)? else {
1734 return Err(MnemoError::Invalid(format!("no task {slug:?}")));
1735 };
1736 let t = Task::from_memory(&m).expect("a task");
1737 let to = status.unwrap_or(&t.status).to_string();
1738 if status.is_none() && note.is_none() {
1739 return Err(MnemoError::Invalid("give a status or a note".into()));
1740 }
1741 if token.is_some() && t.owner.as_deref() != Some(agent.as_str()) {
1744 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1745 }
1746 let changing = to != t.status;
1747 if changing && !TASK_TRANSITIONS.contains(&(t.status.as_str(), to.as_str())) {
1748 return Err(MnemoError::Invalid(format!(
1749 "a task can't go from {} to {to}",
1750 t.status
1751 )));
1752 }
1753 if changing && t.status == task_status::QUEUED {
1754 return Err(MnemoError::Invalid(
1755 "a queued task is taken with `task next`".into(),
1756 ));
1757 }
1758 let topic = task_topic(slug);
1759 let claim = self.find_claim(&topic)?;
1760 let live = claim.as_ref().filter(|c| is_live(c, now));
1761 let claim_token = claim
1762 .as_ref()
1763 .and_then(|c| meta_string(c, MNEMO_META_CLAIM_TOKEN));
1764 let held_by_owner = live.is_some_and(|c| meta_string(c, MNEMO_META_HOLDER) == t.owner);
1765 let is_owner = t.owner.as_deref() == Some(agent.as_str());
1766 let is_creator = t.creator == agent;
1767 let by_owner = if changing && t.status == task_status::READY {
1769 if !(is_creator || (is_owner && t.pre_approved)) {
1771 return Err(MnemoError::Invalid(format!(
1772 "{slug} waits for its creator ({}) to set done",
1773 t.creator
1774 )));
1775 }
1776 false
1777 } else if changing && to == task_status::QUEUED && !is_owner {
1778 if let Some(c) = live {
1780 return Err(MnemoError::Invalid(format!(
1781 "{slug} is {}'s, and its claim is live until {}; only its owner can hand \
1782 it back before then",
1783 t.owner.as_deref().unwrap_or("its owner"),
1784 crate::memory::date_time_of(effective_expiry(c, now).unwrap_or(now))
1785 )));
1786 }
1787 false
1788 } else if t.status == task_status::DONE || (!changing && t.status == task_status::READY) {
1789 if !(is_creator || is_owner) {
1791 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1792 }
1793 false
1794 } else if !changing && is_creator && !is_owner {
1795 false } else if t.status == task_status::QUEUED {
1797 if !is_creator {
1799 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1800 }
1801 false
1802 } else {
1803 if !is_owner {
1804 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1805 }
1806 true
1807 };
1808 let mut renew_token = None;
1815 if by_owner {
1816 let token_ok = token.is_none_or(|tk| claim_token.as_deref() == Some(tk));
1817 if live.is_some() && !held_by_owner {
1818 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1819 }
1820 if !token_ok {
1821 return Ok(TaskOutcome::Lost(TaskLost::OtherToken));
1822 }
1823 if held_by_owner {
1824 renew_token = claim_token.clone();
1825 }
1826 }
1827 let mut m = m;
1828 let mut extra: Vec<(&str, &str)> = Vec::new();
1829 if let Some(n) = note {
1830 extra.push(("note", n));
1831 }
1832 Self::task_history(&mut m, &t.status, &to, &agent, now, &extra);
1833 m.metadata
1834 .insert(MNEMO_META_STATUS.into(), Value::String(to.clone()));
1835 if to == task_status::QUEUED {
1836 m.metadata.remove(MNEMO_META_OWNER);
1837 }
1838 let id = m.id;
1839 self.put(m)?;
1840 let releases =
1841 [task_status::READY, task_status::DONE, task_status::QUEUED].contains(&to.as_str());
1842 let mut held: Option<TaskClaim> = None;
1843 match (releases, by_owner, renew_token) {
1844 (true, _, Some(tk)) => {
1845 self.release(&topic, &tk)?;
1846 }
1847 (true, _, None) => {
1848 if let Some(mut c) = self.find_claim(&topic)? {
1850 if is_live(&c, now)
1851 && meta_string(&c, MNEMO_META_HOLDER) == t.owner
1852 && to == task_status::DONE
1853 {
1854 c.metadata.remove(MNEMO_META_CLAIM_TOKEN);
1855 c.metadata
1856 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
1857 self.put(c)?;
1858 }
1859 }
1860 }
1861 (false, true, Some(tk)) => {
1862 if let ClaimStatus::Held { expires_at } =
1863 self.renew(&topic, &tk, Some(TASK_CLAIM_TTL))?
1864 {
1865 held = Some(TaskClaim {
1866 token: tk,
1867 expires_at,
1868 retaken: false,
1869 });
1870 }
1871 }
1872 (false, true, None) => {
1873 if let ClaimOutcome::Claimed { token, expires_at } =
1876 self.claim(&topic, Some(TASK_CLAIM_TTL))?
1877 {
1878 held = Some(TaskClaim {
1879 token,
1880 expires_at,
1881 retaken: true,
1882 });
1883 }
1884 }
1885 (false, false, _) => {}
1886 }
1887 Ok(TaskOutcome::Updated(
1888 Box::new(Task::from_memory(&self.get(&id)?).expect("a task")),
1889 held,
1890 ))
1891 }
1892}
1893
1894use crate::memory::{
1897 HOP_CAP, MNEMO_META_WAKES, MNEMO_META_WAKE_PAUSED, MNEMO_META_WARNED_EXPIRY, PAIR_BURST,
1898 PAIR_BURST_SECS, TASK_CLAIM_WARN_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
1899};
1900
1901#[derive(Debug, Clone, Default, PartialEq)]
1904#[non_exhaustive]
1905pub struct NewWork {
1906 pub messages: Vec<Message>,
1908 pub tasks: Vec<Task>,
1910 pub lapsing: Vec<Claim>,
1914 pub ready_for_done: Vec<Task>,
1918 pub findings: Vec<super::Finding>,
1922 pub agent: Option<String>,
1925}
1926
1927impl NewWork {
1928 pub fn is_empty(&self) -> bool {
1930 self.messages.is_empty()
1931 && self.tasks.is_empty()
1932 && self.lapsing.is_empty()
1933 && self.ready_for_done.is_empty()
1934 && self.findings.is_empty()
1935 }
1936}
1937
1938#[derive(Debug, Clone, PartialEq, Eq)]
1940pub enum Wake {
1941 Now {
1944 tasks: usize,
1946 messages: usize,
1948 },
1949 Nothing,
1951 Held(&'static str),
1954}
1955
1956impl Mnemo {
1957 pub fn new_work(&mut self, agent: Option<&str>, role: Option<&str>) -> Result<NewWork> {
1960 let now = self.coordination_now();
1961 let unseen =
1962 |d: &str| d == crate::memory::delivery::SENT || d == crate::memory::delivery::DELIVERED;
1963 let mut messages = Vec::new();
1967 for msg in self.inbox(agent, role, true)? {
1968 let broadcast = msg.to == "all" || msg.to.starts_with("role:");
1969 let new = match (broadcast, agent) {
1970 (true, Some(a)) => !seen_by(&self.get(&msg.id)?).iter().any(|s| s == a),
1971 _ => unseen(&msg.delivery),
1972 };
1973 if new {
1974 messages.push(msg);
1975 }
1976 }
1977 let mut tasks = Vec::new();
1978 for t in self.ready_tasks(role)? {
1979 let m = self.get(&t.id)?;
1980 let new = match agent {
1981 Some(a) => !seen_by(&m).iter().any(|s| s == a),
1982 None => meta_string(&m, MNEMO_META_DELIVERY).is_none_or(|d| unseen(&d)),
1983 };
1984 if new {
1985 tasks.push(t);
1986 }
1987 }
1988 let mut ready_for_done = Vec::new();
1991 if let Some(a) = agent {
1992 for t in self.tasks(Some(crate::memory::task_status::READY), None)? {
1993 if t.creator == a && !ready_seen_by(&self.get(&t.id)?).iter().any(|s| s == a) {
1994 ready_for_done.push(t);
1995 }
1996 }
1997 }
1998 let mut findings = Vec::new();
2000 if let (Some(a), Some("planner")) = (agent, role) {
2001 let open = super::FindingFilter {
2002 status: Some(crate::memory::finding_status::OPEN.into()),
2003 ..Default::default()
2004 };
2005 for f in self.findings(&open)? {
2006 if !seen_by(&self.get(&f.record_id)?).iter().any(|s| s == a) {
2007 findings.push(f);
2008 }
2009 }
2010 }
2011 let mut lapsing = Vec::new();
2012 if let Some(a) = agent {
2013 for m in self.coordination_records(MNEMO_META_KIND_CLAIM, None)? {
2014 let topic = meta_string(&m, MNEMO_META_TOPIC).unwrap_or_default();
2015 if !topic.starts_with("task:")
2016 || meta_string(&m, MNEMO_META_HOLDER).as_deref() != Some(a)
2017 || !is_live(&m, now)
2018 {
2019 continue;
2020 }
2021 let e = effective_expiry(&m, now).unwrap_or(now);
2022 if e - now <= TASK_CLAIM_WARN_SECS
2023 && meta_i64(&m, MNEMO_META_WARNED_EXPIRY) != Some(e)
2024 {
2025 lapsing.push(Claim {
2026 topic,
2027 holder: a.to_string(),
2028 expires_at: e,
2029 lease: meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
2030 });
2031 }
2032 }
2033 }
2034 Ok(NewWork {
2035 messages,
2036 tasks,
2037 lapsing,
2038 ready_for_done,
2039 findings,
2040 agent: agent.map(str::to_string),
2041 })
2042 }
2043
2044 pub fn mark_shown(&mut self, work: &NewWork) -> Result<()> {
2049 if self.read_only {
2050 return Err(MnemoError::ReadOnly);
2051 }
2052 let ids: Vec<Ulid> = work.messages.iter().map(|m| m.id).collect();
2053 let who = work.agent.clone().or_else(|| self.author.clone());
2055 let author = std::mem::replace(&mut self.author, who.clone());
2056 let r = self.mark_seen(&ids);
2057 self.author = author;
2058 r?;
2059 for t in &work.tasks {
2060 let mut m = self.get(&t.id)?;
2061 match who.clone() {
2062 Some(a) => {
2064 if add_seen_by(&mut m, &a) {
2065 self.put(m)?;
2066 }
2067 }
2068 None => {
2069 m.metadata.insert(
2070 MNEMO_META_DELIVERY.into(),
2071 Value::String(crate::memory::delivery::SEEN.into()),
2072 );
2073 self.put(m)?;
2074 }
2075 }
2076 }
2077 if let Some(a) = &who {
2079 for f in &work.findings {
2080 let mut m = self.get(&f.record_id)?;
2081 if add_seen_by(&mut m, a) {
2082 self.put(m)?;
2083 }
2084 }
2085 }
2086 if let Some(a) = &who {
2088 for t in &work.ready_for_done {
2089 let mut m = self.get(&t.id)?;
2090 let mut v = ready_seen_by(&m);
2091 if v.iter().any(|s| s == a) {
2092 continue;
2093 }
2094 v.push(a.clone());
2095 m.metadata.insert(
2096 crate::memory::MNEMO_META_READY_SEEN_BY.into(),
2097 Value::Array(v.into_iter().map(Value::String).collect()),
2098 );
2099 self.put(m)?;
2100 }
2101 }
2102 for c in &work.lapsing {
2103 if let Some(mut m) = self.find_claim(&c.topic)? {
2104 m.metadata
2105 .insert(MNEMO_META_WARNED_EXPIRY.into(), Value::from(c.expires_at));
2106 self.put(m)?;
2107 }
2108 }
2109 Ok(())
2110 }
2111
2112 pub fn wake_paused(&mut self) -> Result<Option<(String, i64)>> {
2115 let Some(m) = self
2116 .about_in(crate::memory::VisibilitySet::ALL)?
2117 .into_iter()
2118 .find(is_manifest)
2119 else {
2120 return Ok(None);
2121 };
2122 Ok(m.metadata.get(MNEMO_META_WAKE_PAUSED).map(|v| {
2123 (
2124 v.get("by")
2125 .and_then(Value::as_str)
2126 .unwrap_or("")
2127 .to_string(),
2128 v.get("at").and_then(Value::as_i64).unwrap_or(0),
2129 )
2130 }))
2131 }
2132
2133 pub fn set_wake_paused(&mut self, paused: bool) -> Result<WriteOutcome> {
2137 if self.read_only {
2138 return Err(MnemoError::ReadOnly);
2139 }
2140 let Some(mut m) = self
2141 .about_in(crate::memory::VisibilitySet::ALL)?
2142 .into_iter()
2143 .find(is_manifest)
2144 else {
2145 return Err(MnemoError::Invalid(
2146 "this brain has no manifest to record the pause on".into(),
2147 ));
2148 };
2149 if m.metadata.contains_key(MNEMO_META_WAKE_PAUSED) == paused {
2150 return Ok(WriteOutcome::Unchanged);
2151 }
2152 if paused {
2153 let mut v = Map::new();
2154 v.insert(
2155 "by".into(),
2156 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
2157 );
2158 v.insert("at".into(), Value::from(self.coordination_now()));
2159 m.metadata
2160 .insert(MNEMO_META_WAKE_PAUSED.into(), Value::Object(v));
2161 } else {
2162 m.metadata.remove(MNEMO_META_WAKE_PAUSED);
2163 }
2164 self.put(m)?;
2165 Ok(WriteOutcome::Updated)
2166 }
2167
2168 pub fn wake(&mut self, agent: &str, role: Option<&str>) -> Result<Wake> {
2183 if self.read_only {
2184 return Err(MnemoError::ReadOnly);
2185 }
2186 let now = self.coordination_now();
2187 let sent = crate::memory::delivery::SENT;
2188 let mut tasks = Vec::new();
2189 for t in self.ready_tasks(role)? {
2190 let m = self.get(&t.id)?;
2191 if t.pre_approved
2192 && meta_string(&m, MNEMO_META_DELIVERY).as_deref() == Some(sent)
2193 && !seen_by(&m).iter().any(|s| s == agent)
2194 {
2195 tasks.push(t.id);
2196 }
2197 }
2198 let all_msgs: Vec<Message> = self
2199 .messages()?
2200 .iter()
2201 .filter_map(Message::from_memory)
2202 .collect();
2203 let candidates: Vec<&Message> = all_msgs
2204 .iter()
2205 .filter(|m| m.to == agent && m.from != agent)
2206 .filter(|m| m.status == crate::memory::MESSAGE_UNREAD && m.delivery == sent)
2207 .collect();
2208 if tasks.is_empty() && candidates.is_empty() {
2209 return Ok(Wake::Nothing);
2210 }
2211 if self.wake_paused()?.is_some() {
2212 return Ok(Wake::Held("paused"));
2213 }
2214 let burst = |a: &str, b: &str| {
2215 all_msgs
2216 .iter()
2217 .filter(|m| now - m.created_at <= PAIR_BURST_SECS)
2218 .filter(|m| (m.from == a && m.to == b) || (m.from == b && m.to == a))
2219 .count()
2220 >= PAIR_BURST
2221 };
2222 let mut reason = None;
2223 let messages: Vec<Ulid> = candidates
2224 .iter()
2225 .filter(|m| {
2226 let reply = m.conversation != m.id.to_string();
2227 if reply && m.hops > HOP_CAP {
2228 reason = Some("the thread reached its hop cap");
2229 return false;
2230 }
2231 if burst(&m.from, &m.to) {
2232 reason = Some("a burst of messages between two agents");
2233 return false;
2234 }
2235 true
2236 })
2237 .map(|m| m.id)
2238 .collect();
2239 if tasks.is_empty() && messages.is_empty() {
2240 return Ok(Wake::Held(reason.unwrap_or("a guardrail")));
2241 }
2242 let presence = self
2244 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(agent))?
2245 .into_iter()
2246 .next();
2247 let mut wakes: Vec<i64> = presence
2248 .as_ref()
2249 .and_then(|m| m.metadata.get(MNEMO_META_WAKES))
2250 .and_then(Value::as_array)
2251 .map(|a| a.iter().filter_map(Value::as_i64).collect())
2252 .unwrap_or_default();
2253 wakes.retain(|t| now - t < 3600 && *t <= now);
2254 if wakes.len() >= WAKE_PER_HOUR {
2255 return Ok(Wake::Held("the hourly limit of wake-ups"));
2256 }
2257 if wakes.iter().any(|t| now - t < WAKE_COOLDOWN_SECS) {
2258 return Ok(Wake::Held("the cooldown between wake-ups"));
2259 }
2260 wakes.push(now);
2261 let delivered = Value::String(crate::memory::delivery::DELIVERED.into());
2262 for id in tasks.iter().chain(messages.iter()) {
2263 let mut m = self.get(id)?;
2264 m.metadata
2265 .insert(MNEMO_META_DELIVERY.into(), delivered.clone());
2266 self.put(m)?;
2267 }
2268 let w = Value::Array(wakes.into_iter().map(Value::from).collect());
2269 match presence {
2270 Some(mut m) => {
2271 m.metadata.insert(MNEMO_META_WAKES.into(), w);
2272 self.put(m)?;
2273 }
2274 None => {
2275 let mut meta = Map::new();
2276 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.to_string()));
2277 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(0));
2278 meta.insert(MNEMO_META_PRESENCE_LOCK.into(), Value::Bool(false));
2279 meta.insert(MNEMO_META_WAKES.into(), w);
2280 self.put_coordination_with_id(
2281 Ulid::new(),
2282 MNEMO_META_KIND_PRESENCE,
2283 format!("presence {agent}"),
2284 meta,
2285 )?;
2286 }
2287 }
2288 Ok(Wake::Now {
2289 tasks: tasks.len(),
2290 messages: messages.len(),
2291 })
2292 }
2293}
2294
2295#[derive(Debug, Clone, PartialEq, Eq)]
2299#[non_exhaustive]
2300pub struct Stale {
2301 pub id: Ulid,
2303 pub what: String,
2307 pub since: i64,
2309 pub text: String,
2311 pub whose: Option<String>,
2313 pub visibility: String,
2315}
2316
2317impl Mnemo {
2318 pub fn stale(&mut self) -> Result<Vec<Stale>> {
2325 use super::records::{ROW_KIND_ESSENCE, ROW_REVIEW};
2326 let now = self.coordination_now();
2327 let entries: Vec<CatalogEntry> = self
2328 .catalog
2329 .iter()
2330 .filter(|e| !e.deleted)
2331 .filter(|e| {
2332 e.v9.is_none_or(|r| {
2333 r.kind == ROW_KIND_ESSENCE
2334 || r.kind == ROW_KIND_COORDINATION
2335 || r.flags & ROW_REVIEW != 0
2336 })
2337 })
2338 .cloned()
2339 .collect();
2340 let mut out = Vec::new();
2341 for e in entries {
2342 let m = self.read_memory(&e)?;
2343 let Some(since) = crate::memory::stale_since(&m, now) else {
2344 continue;
2345 };
2346 let s = |k: &str| meta_string(&m, k);
2347 let kind = s(MNEMO_META_KIND);
2348 let what = match kind.as_deref() {
2349 Some("essence") => format!(
2350 "essence {}",
2351 s(crate::memory::MNEMO_META_SECTION).unwrap_or_default()
2352 ),
2353 Some(k @ ("task" | "message")) => {
2354 format!("{k} {}", s(MNEMO_META_STATUS).unwrap_or_default())
2355 }
2356 Some(k) => k.to_string(),
2357 None => "fact".to_string(),
2358 };
2359 let whose = match kind.as_deref() {
2360 Some("task") => s(MNEMO_META_OWNER),
2361 Some("message") => s(MNEMO_META_TO),
2362 _ => s(crate::memory::MNEMO_META_AUTHOR),
2363 };
2364 out.push(Stale {
2365 id: m.id,
2366 what,
2367 since,
2368 text: m.content.lines().next().unwrap_or("").to_string(),
2369 whose,
2370 visibility: crate::memory::visibility_of(&m).to_string(),
2371 });
2372 }
2373 out.sort_by_key(|x| (x.since, x.id.0));
2374 Ok(out)
2375 }
2376}
2377
2378#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
2380#[non_exhaustive]
2381pub struct KindCounts {
2382 pub facts: usize,
2384 pub turns: usize,
2386 pub essence: usize,
2388 pub coordination: usize,
2390}
2391
2392impl Mnemo {
2393 pub fn kind_counts(&self) -> KindCounts {
2397 use super::records::{ROW_KIND_ESSENCE, ROW_KIND_THREAD_LINK, ROW_KIND_TURN};
2398 let mut c = KindCounts::default();
2399 for e in self.catalog.iter().filter(|e| !e.deleted) {
2400 match e.v9.map(|r| r.kind) {
2401 Some(ROW_KIND_TURN | ROW_KIND_THREAD_LINK) => c.turns += 1,
2402 Some(ROW_KIND_ESSENCE) => c.essence += 1,
2403 Some(ROW_KIND_COORDINATION) => c.coordination += 1,
2404 _ => c.facts += 1,
2405 }
2406 }
2407 c
2408 }
2409}
2410
2411#[cfg(test)]
2412mod legacy_scan_tests {
2413 use super::is_sentinel;
2414
2415 #[test]
2418 fn the_sentinel_is_told_from_an_ordinary_vector() {
2419 for dims in [4, 32, 384, 768] {
2420 let s = vec![1.0 / (dims as f32).sqrt(); dims];
2421 let (h, _) = crate::veccol::quantize(&s);
2422 assert!(is_sentinel(&h), "{dims}");
2423 let mut v = s.clone();
2424 v[dims / 2] += 0.05;
2425 assert!(!is_sentinel(&crate::veccol::quantize(&v).0), "{dims}");
2426 let flat = vec![0.5; dims];
2427 assert_eq!(
2428 is_sentinel(&crate::veccol::quantize(&flat).0),
2429 dims == 4,
2430 "{dims}"
2431 );
2432 }
2433 assert!(!is_sentinel(&[]));
2434 }
2435}