Module engine 

Core engine surface for power users and adapter authors.

Contains the EngineHandle, configuration, port traits, NoOp stubs, and use-case request/response DTOs. Most consumers only need the ergonomic tier at the crate root.

Example

use mempill::engine::{EngineConfig, NoOpOracle, NoOpVector};

Structs

AuditQueryRequest

Request to query the audit ledger.

AuditQueryResponse

Response from an audit ledger query.

AuditUseCase

Use-case: retrieve ordered audit ledger entries for an agent (or specific claim).

EngineConfig

Configuration for the mempill engine.

EngineHandle

The sole public async entry point for mempill.

IngestClaimRequest

Public write request. Maps to domain Claim at the application boundary.

IngestClaimResponse

Response from a successful claim ingest.

IngestClaimUseCase

Use-case: ingest a new claim from any binding. Generic over persistence and oracle ports; zero-cost dispatch; testable with mocks. Oracle is optional: when None, the oracle-absent branch fires for heavy-path contradiction resolution. The pending store is type-erased via ErasedPendingStore to keep the use-case free of a third type parameter while still being injectable in tests.

NoOpOracle

A no-op oracle that accepts adjudication requests and immediately returns a unit handle.

NoOpVector

A no-op vector store that discards all embeddings and returns empty search results.

PendingAdjudicationRow

A row in the pending_adjudications table.

QueryHistoryRequest

Request to retrieve the full history timeline for a (subject, predicate) subject-line.

QueryHistoryResponse

Response from query_history — the full ordered timeline for a subject-line.

QueryHistoryUseCase

Use-case: retrieve the full ordered history timeline for a (subject, predicate) line.

QueryMemoryRequest

Request to retrieve the current belief for a (subject, predicate) subject-line.

QueryMemoryResponse

Response from a memory query — the canonical belief projection.

QueryMemoryUseCase

Use-case: query the canonical belief for a (subject, predicate) line. Generic over persistence and vector ports. Vector is optional: None = structural-only mode (v0.1 default).

ReconcileRequest

Request to reconcile one or more subject lines.

ReconcileResponse

Response from a reconciliation pass.

ReconcileUseCase

Use-case: run a reconciliation pass over the given subject-lines.

Enums

MemError

Top-level error type for the mempill engine. Every invariant violation surfaces as a typed variant here — never silently swallowed.

Traits

EmbeddingPort

Bring-your-own-embedding port for fuzzy candidate coverage (secondary tier). The engine is fully functional in structural-only mode when this port is absent.

ExtractorPort

Stochastic extractor port. Host-implemented.

OraclePort

The oracle port — pull-based, non-blocking.

PendingAdjudicationPort

The pending-adjudication persistence port — read + write on the pending_adjudications table.

PersistencePort

The persistence port — INSERT-only, agent_id-first. All methods take agent_id as the primary parameter (not a filter). Must enforce: single-writer per agent_id; append-only; atomic commit unit.

VectorPort

Vector persistence seam — kept separate from PersistencePort for model-swap safety.

Type Aliases

BeliefResult

Belief projection result — returned from query_memory.

WriteResult

Write surface result — returned synchronously. For heavy-path ops, disposition = QueuedForAdjudication; final state arrives asynchronously via the oracle callback.