mempill_core/lib.rs
1//! # mempill-core
2//!
3//! Domain engine port traits, configuration, error model, NoOp stubs, use-cases, DTOs,
4//! and the async EngineHandle for the mempill temporally-correct AI-agent memory engine.
5//!
6//! ## Crate Organization
7//!
8//! - `ports/` — Hexagonal port traits (sync; no async fn). Public: visible to adapter crates.
9//! - [`ports::PersistencePort`] — INSERT-only, agent_id-first persistence seam.
10//! - [`ports::OraclePort`] — Pull-based, non-blocking adjudication port.
11//! - [`ports::ExtractorPort`] — Stochastic proposer port (returns proposals, never commits).
12//! - [`ports::EmbeddingPort`] — BYO-embedding port for fuzzy candidate coverage.
13//! - [`ports::VectorPort`] — v0.1 compile-time seam (unimplemented; v0.2 sqlite-vec).
14//! - `config` — [`EngineConfig`] struct with all tunable engine parameters.
15//! - `error` — [`MemError`] enum (thiserror), [`WriteResult`], [`BeliefResult`] aliases.
16//! - `noop` — [`noop::NoOpOracle`], [`noop::NoOpVector`] — do-nothing stubs for tests.
17//! - `application/` — use-cases (IngestClaim, QueryMemory, Reconcile, Audit) + public DTOs.
18//! - `engine_handle` — [`EngineHandle`] async public entry point; bridges async callers to sync core.
19//!
20//! ## Sync Core Convention
21//!
22//! All port traits and engine domain functions are synchronous. Async lives ONLY at the
23//! `EngineHandle` boundary via `tokio::task::spawn_blocking`. The concurrency module
24//! uses `tokio::sync` primitives (Mutex/RwLock) because the lock map is acquired by async
25//! Tokio tasks — this is the lock layer, not the domain layer.
26
27#![warn(missing_docs)]
28
29pub mod application;
30pub mod config;
31pub mod engine_handle;
32pub mod error;
33pub mod noop;
34pub mod ports;
35
36pub(crate) mod concurrency;
37pub(crate) mod engine;
38
39#[cfg(any(test, feature = "test-support"))]
40pub mod testing;
41
42// ── Key public re-exports ─────────────────────────────────────────────────────
43
44pub use application::{
45 AuditQueryRequest, AuditQueryResponse, AuditUseCase, HistoryEntry, IngestClaimRequest,
46 IngestClaimResponse, IngestClaimUseCase, QueryHistoryRequest, QueryHistoryResponse,
47 QueryHistoryUseCase, QueryMemoryRequest, QueryMemoryResponse, QueryMemoryUseCase,
48 ReconcileRequest, ReconcileResponse, ReconcileUseCase,
49};
50pub use config::EngineConfig;
51pub use engine_handle::{EngineHandle, ErasedPendingStore, ErasedPendingStoreAdapter};
52pub use error::{BeliefResult, MemError, WriteResult};
53pub use noop::{NoOpOracle, NoOpVector};
54pub use ports::{
55 EmbeddingPort, ExtractorPort, OraclePort, PendingAdjudicationPort, PendingAdjudicationRow,
56 PersistencePort, Txn, VectorPort,
57};