1#![forbid(unsafe_code)]
50#![warn(missing_docs)]
51#![allow(unknown_lints)]
58#![allow(clippy::chunks_exact_to_as_chunks)]
59
60#[cfg(feature = "embed-candle")]
63pub mod builtin;
64mod cache;
65mod crypto;
66mod embed;
67mod embed_cmd;
68mod error;
69mod format;
70mod freelist;
71pub mod guide;
72mod ident;
73mod index;
74pub mod keys;
75mod keyslot;
76pub mod mcp;
77mod memory;
78mod pager;
79pub mod redact;
80mod result_cache;
81mod session;
82mod shared;
83mod store;
84mod text;
85mod transcript;
86mod veccol;
87mod wal;
88
89#[cfg(feature = "embed-candle")]
90pub use builtin::BuiltinEmbedder;
91pub use crypto::{KdfParams, SecretKind};
92pub use embed::{Embedder, EmbedderIdentity};
93pub use embed_cmd::{EmbedCmd, DEFAULT_EMBED_TIMEOUT};
94pub use error::{MnemoError, Result};
95pub use index::{IndexConfig, IndexInfo};
96pub use memory::{
98 check_caller_key, is_caller_key, is_coordination, valid_agent_id, CALLER_KEYS,
99 COORDINATION_KINDS, MNEMO_META_AS_OF, MNEMO_META_AUTHOR, MNEMO_META_DEFAULT_AGENT,
100 MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_MESSAGE, MNEMO_META_KIND_PRESENCE, MNEMO_META_KIND_TASK,
101 MNEMO_META_REVIEW_BY, MNEMO_META_VISIBILITY, VISIBILITY_LEVELS,
102};
103pub use memory::{date_of, stale_after, stale_since, visibility_of, VisibilitySet};
105pub use memory::{
107 delivery, MESSAGE_ACKED, MESSAGE_ACKED_KEEP_SECS, MESSAGE_BODY_MAX, MESSAGE_PAIR_CARRY_SECS,
108 MESSAGE_SUBJECT_MAX, MESSAGE_UNREAD, MNEMO_META_ACKED_AT, MNEMO_META_CONVERSATION,
109 MNEMO_META_DELIVERY, MNEMO_META_FROM, MNEMO_META_HOPS, MNEMO_META_TO,
110};
111pub use memory::{
113 finding_status, FINDING_BODY_MAX, FINDING_CATEGORIES, FINDING_PRIORITIES, FINDING_TITLE_MAX,
114 MNEMO_META_BATCH, MNEMO_META_CATEGORY, MNEMO_META_FINDING_ID, MNEMO_META_KIND_FINDING,
115 MNEMO_META_PRIORITY, MNEMO_META_TRIAGE, MNEMO_META_TRIAGED_BY, MNEMO_META_VERIFIED_BY,
116 MNEMO_META_VERIFIED_REF,
117};
118pub use memory::{
119 status as essence_status, CommitBatch, CommitReport, EssenceOp, EssenceOpKind, EssenceScope,
120 EssenceSection, ExportedTurn, Filter, FilterTerm, IngestReport, KeyScope, KeyedMemory, Memory,
121 MemoryPatch, MemoryType, Metric, Scope, ScoreWeights, ThreadTurn, TurnPolicy, WriteOutcome,
122 CONTINUATION_TIMELINE_ENTRIES, ESSENCE_DEFAULT_RENDER_BYTES, ESSENCE_SECTION_MAX_BYTES,
123 ESSENCE_TIMELINE_MAX_BYTES, ESSENCE_TRANSITIONS, FINDING_TRANSITIONS, MNEMO_META_CONTINUES,
124 MNEMO_META_INVALID_AT, MNEMO_META_KEY, MNEMO_META_KIND, MNEMO_META_KIND_ESSENCE,
125 MNEMO_META_KIND_THREAD_LINK, MNEMO_META_KIND_TURN, MNEMO_META_LENGTH, MNEMO_META_MARKERS_ONLY,
126 MNEMO_META_NS, MNEMO_META_PART, MNEMO_META_REFS, MNEMO_META_ROLE, MNEMO_META_SECTION,
127 MNEMO_META_SEQ, MNEMO_META_SHA256, MNEMO_META_STATUS, MNEMO_META_STATUS_HISTORY,
128 MNEMO_META_SUPERSEDED_BY, MNEMO_META_SUPERSEDES, MNEMO_META_THREAD, MNEMO_META_TURN_ID,
129 MNEMO_META_UPDATED_AT, TASK_TRANSITIONS, THREAD_TOOL_RESULT_TRUNCATE_BYTES,
130 THREAD_TURN_CHUNK_BYTES,
131};
132pub use memory::{
134 task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_OWNER, MNEMO_META_PRE_APPROVED,
135 MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_CLAIM_WARN_SECS, TASK_DONE_EXPORT_KEEP_SECS,
136 TASK_SLUG_MAX,
137};
138pub use memory::{
140 CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
141 PRESENCE_EVERY_SECS,
142};
143pub use memory::{
145 HOP_CAP, MNEMO_META_WAKE_PAUSED, PAIR_BURST, PAIR_BURST_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
146};
147pub use result_cache::{
148 CacheBudget, CacheFlushPolicy, CachePutOpts, CacheStats, CachedValue, SemanticCachePutOpts,
149 DEFAULT_BATCH_MAX_AGE, DEFAULT_BATCH_MAX_DIRTY, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES,
150 DEFAULT_SEMANTIC_THRESHOLD,
151};
152pub use session::{Role, Session, Turn};
153pub use shared::{sidecar_notes, CancelToken, SharedOptions};
154#[doc(hidden)]
155#[cfg(feature = "dev-hooks")]
156pub use store::BudgetReport;
157pub use store::{
158 slug_of, Alive, Claim, ClaimOutcome, ClaimStatus, KindCounts, Message, NewWork, Presence,
159 Stale, Task, TaskClaim, TaskLost, TaskOutcome, TaskSpec, TaskTaken, Wake,
160};
161pub use store::{valid_finding_id, Finding, FindingFilter, FindingSpec};
163pub use store::{
164 CloseError, CompactReport, IndexCheck, Mnemo, MnemoConfig, RecallMode, RecallRequest,
165 RecallResponse, RecallResult, ReembedReport, SharedMnemo, SnapshotInfo, Stats, StatsSummary,
166 VerifyReport, DEFAULT_KEYWORD_WEIGHT, DEFAULT_TEXT_KEYWORD_WEIGHT,
167 DEFAULT_TURN_COMPRESS_AFTER_SECS, DEFAULT_VECTOR_CACHE_BUDGET, INDEX_PERSIST_EVERY_CHANGES,
168 INDEX_PERSIST_EVERY_COMMITS, V9_ANN_MIN_FACTS, V9_RERANK_PER_HIT,
169};
170pub use text::{KeywordIndex, KeywordTokenizer};
171pub use transcript::{
172 read_transcript, read_transcript_with, ToolResults, TranscriptFormat, TranscriptOptions,
173};
174
175pub use ulid::Ulid;
177
178mod fsync_counter {
190 use std::cell::Cell;
191
192 thread_local! {
193 static COUNT: Cell<u64> = const { Cell::new(0) };
194 }
195
196 pub(crate) fn bump() {
198 COUNT.with(|c| c.set(c.get().wrapping_add(1)));
199 }
200
201 pub(crate) fn count() -> u64 {
203 COUNT.with(|c| c.get())
204 }
205}
206
207pub(crate) use fsync_counter::{bump as bump_fsync, count as fsync_count};
208
209#[derive(Debug, Clone, Copy, PartialEq, Eq)]
223pub struct BuildInfo {
224 pub version: &'static str,
226 pub target: &'static str,
229 pub aes_backend: &'static str,
236 pub polyval_backend: &'static str,
239}
240
241pub fn build_info() -> BuildInfo {
246 BuildInfo {
247 version: env!("CARGO_PKG_VERSION"),
248 target: TARGET_TRIPLE,
249 aes_backend: aes_backend_name(),
250 polyval_backend: polyval_backend_name(),
251 }
252}
253
254const TARGET_TRIPLE: &str = {
260 if cfg!(all(target_arch = "aarch64", target_os = "macos")) {
265 "aarch64-apple-darwin"
266 } else if cfg!(all(target_arch = "aarch64", target_os = "linux")) {
267 "aarch64-unknown-linux-gnu"
268 } else if cfg!(all(target_arch = "x86_64", target_os = "macos")) {
269 "x86_64-apple-darwin"
270 } else if cfg!(all(target_arch = "x86_64", target_os = "linux")) {
271 "x86_64-unknown-linux-gnu"
272 } else if cfg!(all(target_arch = "x86_64", target_os = "windows")) {
273 "x86_64-pc-windows-msvc"
274 } else {
275 "unknown"
276 }
277};
278
279const fn aes_backend_name() -> &'static str {
280 if cfg!(aes_armv8) {
281 "armv8 hardware"
282 } else if cfg!(target_arch = "aarch64") {
283 "armv8 software (constant-time fallback)"
287 } else if cfg!(target_arch = "x86_64") {
288 "x86_64 AES-NI (runtime detect)"
293 } else {
294 "portable software"
295 }
296}
297
298const fn polyval_backend_name() -> &'static str {
299 if cfg!(polyval_armv8) {
300 "armv8 PMULL hardware"
301 } else if cfg!(target_arch = "aarch64") {
302 "armv8 software (constant-time fallback)"
303 } else if cfg!(target_arch = "x86_64") {
304 "x86_64 CLMUL (runtime detect)"
305 } else {
306 "portable software"
307 }
308}
309
310#[cfg(feature = "dev-hooks")]
314#[doc(hidden)]
315pub fn __fsync_count() -> u64 {
316 fsync_count()
317}
318
319#[cfg(any(test, feature = "failpoints"))]
326#[doc(hidden)]
327pub mod __failpoints {
328 pub fn set_writes_until_fail(n: i64) {
337 crate::pager::failpoints::set_writes_until_fail(n)
338 }
339
340 pub fn set_writes_until_fail_n(n: i64, count: u32) {
342 crate::pager::failpoints::set_writes_until_fail_n(n, count)
343 }
344
345 pub fn set_writes_failing(ns: &[u64]) {
348 crate::pager::failpoints::set_writes_failing(ns)
349 }
350
351 pub fn writes_seen() -> u64 {
354 crate::pager::failpoints::writes_seen()
355 }
356
357 pub fn set_page_read_fails(page: u64, count: u32) {
361 crate::pager::failpoints::set_page_read_fails(page, count)
362 }
363
364 thread_local! {
365 static AFTER_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
366 const { std::cell::RefCell::new(None) };
367 static BEFORE_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
368 const { std::cell::RefCell::new(None) };
369 }
370
371 pub fn before_next_shared_commit(f: impl FnOnce() + 'static) {
376 BEFORE_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
377 }
378
379 pub(crate) fn run_before_shared_commit() {
380 if let Some(f) = BEFORE_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
381 f();
382 }
383 }
384
385 pub fn after_next_shared_commit(f: impl FnOnce() + 'static) {
389 AFTER_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
390 }
391
392 pub(crate) fn run_after_shared_commit() {
393 if let Some(f) = AFTER_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
394 f();
395 }
396 }
397
398 thread_local! {
399 static NEXT_TEMP_NAME: std::cell::RefCell<Option<std::path::PathBuf>> =
400 const { std::cell::RefCell::new(None) };
401 }
402
403 pub fn set_next_temp_name(path: impl Into<std::path::PathBuf>) {
408 NEXT_TEMP_NAME.with(|n| *n.borrow_mut() = Some(path.into()));
409 }
410
411 pub(crate) fn take_next_temp_name() -> Option<std::path::PathBuf> {
412 NEXT_TEMP_NAME.with(|n| n.borrow_mut().take())
413 }
414
415 thread_local! {
416 static SHARED_MAIN_TRIES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
417 static SHARED_REPLACED: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
418 }
419
420 pub fn shared_main_tries() -> u64 {
423 SHARED_MAIN_TRIES.with(|c| c.get())
424 }
425
426 pub(crate) fn count_shared_main_try() {
427 SHARED_MAIN_TRIES.with(|c| c.set(c.get() + 1));
428 }
429
430 pub fn set_shared_replaced(n: u64) {
434 SHARED_REPLACED.with(|c| c.set(n));
435 }
436
437 thread_local! {
438 static EUID_OVERRIDE: std::cell::Cell<Option<u32>> = const { std::cell::Cell::new(None) };
439 }
440
441 pub fn set_euid_override(uid: Option<u32>) {
446 EUID_OVERRIDE.with(|c| c.set(uid));
447 }
448
449 #[cfg(unix)]
451 pub(crate) fn euid_override() -> Option<u32> {
452 EUID_OVERRIDE.with(|c| c.get())
453 }
454
455 thread_local! {
456 static PATH_CHECK_FAILURES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
457 }
458
459 pub fn set_path_check_failures(n: u64) {
463 PATH_CHECK_FAILURES.with(|c| c.set(n));
464 }
465
466 pub fn path_check_failures_left() -> u64 {
468 PATH_CHECK_FAILURES.with(|c| c.get())
469 }
470
471 pub(crate) fn take_path_check_failure() -> bool {
472 PATH_CHECK_FAILURES.with(|c| {
473 let n = c.get();
474 if n > 0 {
475 c.set(n - 1);
476 }
477 n > 0
478 })
479 }
480
481 pub(crate) fn take_shared_replaced() -> bool {
482 SHARED_REPLACED.with(|c| {
483 let n = c.get();
484 if n > 0 {
485 c.set(n - 1);
486 }
487 n > 0
488 })
489 }
490}
491
492#[cfg(any(test, feature = "failpoints"))]
498#[doc(hidden)]
499pub mod __shared {
500 use std::path::{Path, PathBuf};
501
502 use crate::shared::{BrainLocks, Call, Held, LockKind};
503 use crate::{Result, SharedOptions};
504
505 pub const SUFFIX: &str = crate::shared::testing::SUFFIX;
507 pub const INTENT: &str = crate::shared::testing::INTENT;
508 pub const LOCK_INFO: &str = crate::shared::testing::LOCK_INFO;
509 pub const VALVE: &str = crate::shared::testing::VALVE;
511
512 pub const WINDOWS_OLD_RENAME: bool = crate::shared::WINDOWS_OLD_RENAME;
514
515 pub fn sidecar_path(brain: &Path) -> PathBuf {
517 crate::shared::testing::sidecar_path(brain)
518 }
519
520 pub fn classify_synced(path: &Path, home: &Path) -> Option<String> {
522 crate::shared::testing::classify_synced(path, home)
523 }
524
525 pub fn linux_fs_allowed(magic: u32) -> bool {
527 crate::shared::testing::linux_fs_allowed(magic)
528 }
529
530 #[derive(Debug)]
532 pub struct Locks(BrainLocks);
533
534 impl Locks {
535 pub fn new(path: &Path, opts: &SharedOptions) -> Result<Self> {
536 BrainLocks::new(path, opts).map(Locks)
537 }
538 pub fn for_plain(path: &Path, opts: &SharedOptions) -> Result<Self> {
540 BrainLocks::for_plain(path, opts).map(Locks)
541 }
542 pub fn valve_takes(&self) -> u64 {
544 self.0.valve_takes()
545 }
546 pub fn shared(&mut self, opts: &SharedOptions) -> Result<Lock> {
547 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
548 self.0.acquire(LockKind::Shared, &mut call).map(Lock)
549 }
550 pub fn exclusive(&mut self, opts: &SharedOptions) -> Result<Lock> {
551 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
552 self.0.acquire(LockKind::Exclusive, &mut call).map(Lock)
553 }
554 pub fn has_sidecar(&self) -> bool {
555 self.0.has_sidecar()
556 }
557 pub fn sidecar_path(&self) -> Option<PathBuf> {
558 self.0.sidecar_path().map(Path::to_path_buf)
559 }
560 pub fn notices(&self) -> Vec<String> {
561 self.0.notices().to_vec()
562 }
563 }
564
565 pub struct Lock(Held);
567
568 impl Lock {
569 pub fn announce(&mut self, op: &str) {
570 self.0.announce(op)
571 }
572 pub fn file(&self) -> &std::fs::File {
573 self.0.file()
574 }
575 }
576}
577
578#[doc(hidden)]
582pub mod __wal {
583 pub const PAGE_SIZE: usize = crate::format::PAGE_SIZE;
585
586 pub type Frame = (u64, Vec<u8>);
588
589 pub fn txn_byte_len(n: usize) -> u64 {
591 crate::wal::txn_byte_len(n, PAGE_SIZE)
592 }
593
594 pub fn commit(
596 file: &mut std::fs::File,
597 wal_pages: u64,
598 txn_id: u64,
599 frames: &[Frame],
600 ) -> crate::Result<()> {
601 crate::wal::commit(file, 0, wal_pages, txn_id, frames)
602 }
603
604 pub fn recover(
607 file: &mut std::fs::File,
608 wal_pages: u64,
609 wal_seq: u64,
610 ) -> crate::Result<Option<Vec<Frame>>> {
611 crate::wal::recover(file, 0, wal_pages, wal_seq)
612 }
613}
614
615#[doc(hidden)]
624pub mod __fuzz {
625 pub fn parse_header(bytes: &[u8]) -> crate::Result<()> {
629 crate::format::Header::from_page(bytes).map(|_| ())
630 }
631
632 pub fn wal_recover_bytes(region: &[u8], wal_seq: u64) -> crate::Result<()> {
637 crate::wal::recover_bytes(region, wal_seq).map(|_| ())
638 }
639
640 pub fn decode_memory(bytes: &[u8]) -> crate::Result<()> {
642 rmp_serde::from_slice::<crate::Memory>(bytes)
643 .map(|_| ())
644 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
645 }
646
647 pub fn decode_v9_memory(bytes: &[u8]) -> crate::Result<()> {
651 let plain = crate::store::plain_record(bytes)?;
652 rmp_serde::from_slice::<crate::Memory>(&plain)
653 .map(|_| ())
654 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
655 }
656
657 pub fn decode_cache_entry(bytes: &[u8]) -> crate::Result<()> {
660 rmp_serde::from_slice::<crate::result_cache::CacheEntry>(bytes)
661 .map(|_| ())
662 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
663 }
664
665 pub fn decode_cache_directory(bytes: &[u8]) -> crate::Result<()> {
668 rmp_serde::from_slice::<Vec<crate::result_cache::CacheDirectoryEntry>>(bytes)
669 .map(|_| ())
670 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
671 }
672
673 pub fn decode_index_layout2(bytes: &[u8]) -> crate::Result<()> {
678 let idx = crate::index::IvfPqIndex::read_layout2(&mut &bytes[..], bytes.len() as u64)?;
679 exercise_index(idx)
680 }
681
682 pub fn mutate_index_layout2(edits: &[u8]) -> crate::Result<()> {
688 static BASE: std::sync::OnceLock<Vec<u8>> = std::sync::OnceLock::new();
689 let base = BASE.get_or_init(|| {
690 let vecs: Vec<(u128, Vec<f32>)> = (0..300u32)
691 .map(|i| {
692 let x = i as f32;
693 (
694 i as u128 + 1,
695 vec![
696 1.0 + (x * 0.37).sin(),
697 (x * 0.11).cos(),
698 (x * 0.07).sin(),
699 0.5,
700 ],
701 )
702 })
703 .collect();
704 let items: Vec<(u128, &[f32])> = vecs.iter().map(|(i, v)| (*i, v.as_slice())).collect();
705 let idx = crate::index::IvfPqIndex::build(4, &items, crate::IndexConfig::default())
706 .expect("the seed index builds");
707 let mut out = Vec::new();
708 idx.write_layout2(&mut out);
709 out
710 });
711 let mut body = base.clone();
712 let mut chunks = edits.chunks_exact(3);
713 for e in chunks.by_ref() {
714 let at = u16::from_le_bytes([e[0], e[1]]) as usize % body.len();
715 body[at] ^= e[2];
716 }
717 match chunks.remainder() {
718 [c] => body.truncate(body.len() * *c as usize / 256),
719 [a, b] => body.truncate(body.len() * u16::from_le_bytes([*a, *b]) as usize / 65536),
720 _ => {}
721 }
722 decode_index_layout2(&body)
723 }
724
725 fn exercise_index(mut idx: crate::index::IvfPqIndex) -> crate::Result<()> {
726 let dims = idx.dims();
727 if dims == 0 || dims > 4096 {
728 return Ok(());
729 }
730 let q = vec![0.5f32; dims];
731 let _ = idx.query(&q, None, None);
732 let first = idx.ids().next();
733 idx.add(u128::MAX - 1, &q);
734 if let Some(id) = first {
735 idx.remove(id);
736 }
737 let _ = idx.query(&q, Some(2), Some(8));
738 let mut out = Vec::new();
739 idx.write_layout2(&mut out);
740 crate::index::IvfPqIndex::read_layout2(&mut &out[..], out.len() as u64)
741 .expect("an index this build wrote decodes again");
742 Ok(())
743 }
744
745 pub fn parse_mcp_request_line(line: &str) -> Result<(), String> {
749 crate::mcp::__fuzz_parse_request_line(line)
750 }
751}