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, Mnemo, MnemoConfig, RecallMode, RecallRequest, RecallResponse,
165 RecallResult, ReembedReport, SharedMnemo, SnapshotInfo, Stats, StatsSummary, VerifyReport,
166 DEFAULT_KEYWORD_WEIGHT, DEFAULT_TEXT_KEYWORD_WEIGHT, DEFAULT_TURN_COMPRESS_AFTER_SECS,
167 DEFAULT_VECTOR_CACHE_BUDGET, INDEX_PERSIST_EVERY_CHANGES, INDEX_PERSIST_EVERY_COMMITS,
168 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 thread_local! {
358 static AFTER_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
359 const { std::cell::RefCell::new(None) };
360 static BEFORE_SHARED_COMMIT: std::cell::RefCell<Option<Box<dyn FnOnce()>>> =
361 const { std::cell::RefCell::new(None) };
362 }
363
364 pub fn before_next_shared_commit(f: impl FnOnce() + 'static) {
369 BEFORE_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
370 }
371
372 pub(crate) fn run_before_shared_commit() {
373 if let Some(f) = BEFORE_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
374 f();
375 }
376 }
377
378 pub fn after_next_shared_commit(f: impl FnOnce() + 'static) {
382 AFTER_SHARED_COMMIT.with(|c| *c.borrow_mut() = Some(Box::new(f)));
383 }
384
385 pub(crate) fn run_after_shared_commit() {
386 if let Some(f) = AFTER_SHARED_COMMIT.with(|c| c.borrow_mut().take()) {
387 f();
388 }
389 }
390
391 thread_local! {
392 static NEXT_TEMP_NAME: std::cell::RefCell<Option<std::path::PathBuf>> =
393 const { std::cell::RefCell::new(None) };
394 }
395
396 pub fn set_next_temp_name(path: impl Into<std::path::PathBuf>) {
401 NEXT_TEMP_NAME.with(|n| *n.borrow_mut() = Some(path.into()));
402 }
403
404 pub(crate) fn take_next_temp_name() -> Option<std::path::PathBuf> {
405 NEXT_TEMP_NAME.with(|n| n.borrow_mut().take())
406 }
407
408 thread_local! {
409 static SHARED_MAIN_TRIES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
410 static SHARED_REPLACED: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
411 }
412
413 pub fn shared_main_tries() -> u64 {
416 SHARED_MAIN_TRIES.with(|c| c.get())
417 }
418
419 pub(crate) fn count_shared_main_try() {
420 SHARED_MAIN_TRIES.with(|c| c.set(c.get() + 1));
421 }
422
423 pub fn set_shared_replaced(n: u64) {
427 SHARED_REPLACED.with(|c| c.set(n));
428 }
429
430 thread_local! {
431 static EUID_OVERRIDE: std::cell::Cell<Option<u32>> = const { std::cell::Cell::new(None) };
432 }
433
434 pub fn set_euid_override(uid: Option<u32>) {
439 EUID_OVERRIDE.with(|c| c.set(uid));
440 }
441
442 #[cfg(unix)]
444 pub(crate) fn euid_override() -> Option<u32> {
445 EUID_OVERRIDE.with(|c| c.get())
446 }
447
448 thread_local! {
449 static PATH_CHECK_FAILURES: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
450 }
451
452 pub fn set_path_check_failures(n: u64) {
456 PATH_CHECK_FAILURES.with(|c| c.set(n));
457 }
458
459 pub fn path_check_failures_left() -> u64 {
461 PATH_CHECK_FAILURES.with(|c| c.get())
462 }
463
464 pub(crate) fn take_path_check_failure() -> bool {
465 PATH_CHECK_FAILURES.with(|c| {
466 let n = c.get();
467 if n > 0 {
468 c.set(n - 1);
469 }
470 n > 0
471 })
472 }
473
474 pub(crate) fn take_shared_replaced() -> bool {
475 SHARED_REPLACED.with(|c| {
476 let n = c.get();
477 if n > 0 {
478 c.set(n - 1);
479 }
480 n > 0
481 })
482 }
483}
484
485#[cfg(any(test, feature = "failpoints"))]
491#[doc(hidden)]
492pub mod __shared {
493 use std::path::{Path, PathBuf};
494
495 use crate::shared::{BrainLocks, Call, Held, LockKind};
496 use crate::{Result, SharedOptions};
497
498 pub const SUFFIX: &str = crate::shared::testing::SUFFIX;
500 pub const INTENT: &str = crate::shared::testing::INTENT;
501 pub const LOCK_INFO: &str = crate::shared::testing::LOCK_INFO;
502 pub const VALVE: &str = crate::shared::testing::VALVE;
504
505 pub const WINDOWS_OLD_RENAME: bool = crate::shared::WINDOWS_OLD_RENAME;
507
508 pub fn sidecar_path(brain: &Path) -> PathBuf {
510 crate::shared::testing::sidecar_path(brain)
511 }
512
513 pub fn classify_synced(path: &Path, home: &Path) -> Option<String> {
515 crate::shared::testing::classify_synced(path, home)
516 }
517
518 pub fn linux_fs_allowed(magic: u32) -> bool {
520 crate::shared::testing::linux_fs_allowed(magic)
521 }
522
523 #[derive(Debug)]
525 pub struct Locks(BrainLocks);
526
527 impl Locks {
528 pub fn new(path: &Path, opts: &SharedOptions) -> Result<Self> {
529 BrainLocks::new(path, opts).map(Locks)
530 }
531 pub fn for_plain(path: &Path, opts: &SharedOptions) -> Result<Self> {
533 BrainLocks::for_plain(path, opts).map(Locks)
534 }
535 pub fn valve_takes(&self) -> u64 {
537 self.0.valve_takes()
538 }
539 pub fn shared(&mut self, opts: &SharedOptions) -> Result<Lock> {
540 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
541 self.0.acquire(LockKind::Shared, &mut call).map(Lock)
542 }
543 pub fn exclusive(&mut self, opts: &SharedOptions) -> Result<Lock> {
544 let mut call = Call::new(opts.deadline, opts.cancel.as_ref());
545 self.0.acquire(LockKind::Exclusive, &mut call).map(Lock)
546 }
547 pub fn has_sidecar(&self) -> bool {
548 self.0.has_sidecar()
549 }
550 pub fn sidecar_path(&self) -> Option<PathBuf> {
551 self.0.sidecar_path().map(Path::to_path_buf)
552 }
553 pub fn notices(&self) -> Vec<String> {
554 self.0.notices().to_vec()
555 }
556 }
557
558 pub struct Lock(Held);
560
561 impl Lock {
562 pub fn announce(&mut self, op: &str) {
563 self.0.announce(op)
564 }
565 pub fn file(&self) -> &std::fs::File {
566 self.0.file()
567 }
568 }
569}
570
571#[doc(hidden)]
575pub mod __wal {
576 pub const PAGE_SIZE: usize = crate::format::PAGE_SIZE;
578
579 pub type Frame = (u64, Vec<u8>);
581
582 pub fn txn_byte_len(n: usize) -> u64 {
584 crate::wal::txn_byte_len(n, PAGE_SIZE)
585 }
586
587 pub fn commit(
589 file: &mut std::fs::File,
590 wal_pages: u64,
591 txn_id: u64,
592 frames: &[Frame],
593 ) -> crate::Result<()> {
594 crate::wal::commit(file, 0, wal_pages, txn_id, frames)
595 }
596
597 pub fn recover(
600 file: &mut std::fs::File,
601 wal_pages: u64,
602 wal_seq: u64,
603 ) -> crate::Result<Option<Vec<Frame>>> {
604 crate::wal::recover(file, 0, wal_pages, wal_seq)
605 }
606}
607
608#[doc(hidden)]
617pub mod __fuzz {
618 pub fn parse_header(bytes: &[u8]) -> crate::Result<()> {
622 crate::format::Header::from_page(bytes).map(|_| ())
623 }
624
625 pub fn wal_recover_bytes(region: &[u8], wal_seq: u64) -> crate::Result<()> {
630 crate::wal::recover_bytes(region, wal_seq).map(|_| ())
631 }
632
633 pub fn decode_memory(bytes: &[u8]) -> crate::Result<()> {
635 rmp_serde::from_slice::<crate::Memory>(bytes)
636 .map(|_| ())
637 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
638 }
639
640 pub fn decode_v9_memory(bytes: &[u8]) -> crate::Result<()> {
644 let plain = crate::store::plain_record(bytes)?;
645 rmp_serde::from_slice::<crate::Memory>(&plain)
646 .map(|_| ())
647 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
648 }
649
650 pub fn decode_cache_entry(bytes: &[u8]) -> crate::Result<()> {
653 rmp_serde::from_slice::<crate::result_cache::CacheEntry>(bytes)
654 .map(|_| ())
655 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
656 }
657
658 pub fn decode_cache_directory(bytes: &[u8]) -> crate::Result<()> {
661 rmp_serde::from_slice::<Vec<crate::result_cache::CacheDirectoryEntry>>(bytes)
662 .map(|_| ())
663 .map_err(|e| crate::MnemoError::Serialize(e.to_string()))
664 }
665
666 pub fn parse_mcp_request_line(line: &str) -> Result<(), String> {
670 crate::mcp::__fuzz_parse_request_line(line)
671 }
672}