Struct Engine 

pub struct Engine { /* private fields */ }

Public handle for the protocol-neutral Elastik engine.

Engine is cloneable and owns the startup writer lock for the data root. Dropping the last clone releases the lock.

Implementations

impl Engine

pub fn builder() -> EngineBuilder

Returns a fresh EngineBuilder populated with crate defaults.

pub fn verify_token(&self, token: &[u8]) -> AccessTier

Maps raw token bytes to an AccessTier.

Constant-time comparison against configured tokens. Returns AccessTier::Anon for empty, unrecognized, or invalid token bytes; returns the highest matching tier otherwise.

pub fn allows_read(&self, tier: AccessTier) -> bool

Returns whether tier satisfies the engine’s configured read gate.

Adapters use this for non-world read-only surfaces that still need to mirror /proc/* read policy, such as protocol-local metrics.

pub fn shutdown(&self)

Starts orderly shutdown.

Sets the engine-owned shutdown signal so subscribers (crate::EngineSubscription recv loops, adapter graceful-shutdown futures) can drain in-flight work. Repeated calls are no-ops; only the first call flips the signal.

impl Engine

pub fn list_worlds( &self, tier: AccessTier, ) -> Result<Vec<ValidatedWorldPath>, EngineError>

Lists every canonical world (durable + in-memory) in sorted order.

Errors

• EngineError::Auth if tier is below Read.
• EngineError::TransientStorage / EngineError::Storage / EngineError::InsufficientStorage for storage failures.

pub fn list_worlds_with_prefix( &self, prefix: &str, tier: AccessTier, ) -> Result<Vec<ValidatedWorldPath>, EngineError>

Lists canonical worlds with the supplied canonical prefix.

This is intended for adapters that need a bounded namespace view (for example retained replay) without materializing the full proc-worlds set first. It applies the read gate directly and intentionally bypasses proc-path authorization; do not expose it directly as a network endpoint.

Errors

Same authorization and storage failures as Engine::list_worlds.

pub fn list_worlds_with_prefix_bounded( &self, prefix: &str, tier: AccessTier, max: usize, ) -> Result<Option<Vec<ValidatedWorldPath>>, EngineError>

Lists canonical worlds with the supplied canonical prefix, returning Ok(None) if more than max distinct worlds match.

This is intended for adapter-internal bounded scans. It uses the same read-tier gate as Engine::list_worlds_with_prefix.

pub fn du(&self, tier: AccessTier) -> Result<Vec<WorldUsage>, EngineError>

Returns per-world body byte size, du-style.

Errors

See Engine::list_worlds for the storage-failure variants. Same Read-tier requirement.

pub fn df(&self, tier: AccessTier) -> Result<DfSnapshot, EngineError>

Returns aggregate storage + memory usage, df-style.

Errors

• EngineError::Auth if tier is below Read.

pub fn pool(&self, tier: AccessTier) -> Result<PoolSnapshot, EngineError>

Returns the read-cache + ledger-writer counter snapshot.

Errors

• EngineError::Auth if tier is below Read.

pub fn verify_audit( &self, world: &ValidatedWorldPath, tier: AccessTier, ) -> Result<AuditVerify, EngineError>

Verifies a single world’s HMAC audit chain.

Returns AuditVerify::Valid / AuditVerify::Broken / AuditVerify::NotApplicable (the latter for in-memory worlds with no chain).

Errors

• EngineError::Auth if tier is below Read.
• EngineError::NotFound if world does not exist.
• EngineError::TransientStorage / EngineError::Storage / EngineError::InsufficientStorage for storage failures during verification.

impl Engine

pub fn read( &self, world: &ValidatedWorldPath, tier: AccessTier, ) -> Result<Option<ReadResult>, EngineError>

Reads a world’s full representation.

Returns

• Ok(Some(ReadResult)) if the world exists.
• Ok(None) if the world does not exist (callers that want 404 semantics handle this).

Errors

• EngineError::Auth if tier is below Read.
• EngineError::TransientStorage for SQLite BUSY/LOCKED.
• EngineError::InsufficientStorage for full-disk failures.
• EngineError::Storage for other storage errors.

pub async fn replace( &self, world: &ValidatedWorldPath, representation: Representation, preconditions: Preconditions, tier: AccessTier, ) -> Result<WriteResult, EngineError>

Replaces a world with the provided representation.

Creates the world if it does not exist; otherwise overwrites the body, content type, and headers, then advances the audit chain.

Errors

• EngineError::Auth if tier is below the namespace’s write requirement (Write for home/, Approve for system namespaces).
• EngineError::PayloadTooLarge if the body exceeds the per-world cap.
• EngineError::PreconditionFailed if preconditions reject the write.
• EngineError::QuotaExceeded for durable-storage quota failures.
• EngineError::TransientStorage / EngineError::InsufficientStorage / EngineError::Storage for storage-layer failures.

pub async fn append( &self, world: &ValidatedWorldPath, body: Bytes, preconditions: Preconditions, tier: AccessTier, ) -> Result<WriteResult, EngineError>

Appends bytes to a world’s body and advances the audit chain.

Same auth requirements and error variants as Engine::replace. The world’s content type and metadata headers are unchanged.

Errors

Same as Engine::replace.

pub async fn delete( &self, world: &ValidatedWorldPath, preconditions: Preconditions, tier: AccessTier, ) -> Result<(), EngineError>

Deletes a world with default, empty audit metadata.

Convenience wrapper around the delete transition that records empty content-type and headers in the audit intent. Adapters that need to preserve the deleted representation’s metadata in the audit log should call Engine::delete_traced with a populated crate::DeleteMetadata.

Errors

• EngineError::Auth if tier is below Approve.
• EngineError::AppendOnly for append-only worlds (e.g. var/log/deletes).
• EngineError::PreconditionFailed / EngineError::NotFound.
• EngineError::TransientStorage / EngineError::InsufficientStorage / EngineError::Storage for storage-layer failures.

pub fn subscribe( &self, pattern: &SubscribePattern, tier: AccessTier, since: Option<u64>, ) -> Result<EngineSubscription, EngineError>

Subscribes to change events matching pattern.

If since is Some(id), the subscription replays every event with id > since from the in-memory ring before switching to the live stream. Replay is bounded by the configured listen_replay_max; if since is older than the ring’s floor, the first recv call yields a crate::SubscriptionRecvError::Lagged error.

The returned EngineSubscription holds a subscription slot until dropped; drop it promptly when finished so other subscribers can join.

Errors

• EngineError::Auth if tier is below Read.
• EngineError::SubscriptionLimit if the slot pool is full.
• EngineError::ShuttingDown if Engine::shutdown has been called.

impl Engine

pub async fn replace_traced<H: EngineWriteTraceHooks + ?Sized>( &self, world: &ValidatedWorldPath, representation: Representation, preconditions: Preconditions, tier: AccessTier, hooks: &H, ) -> Result<WriteResult, EngineError>

Same as crate::Engine::replace but invokes hooks on each protocol phase.

Adapters use this to drive structured trace output or per-operation metrics without paying the hook cost in non-traced call sites.

Errors

Same as crate::Engine::replace.

pub async fn append_traced<H: EngineWriteTraceHooks + ?Sized>( &self, world: &ValidatedWorldPath, body: Bytes, preconditions: Preconditions, tier: AccessTier, hooks: &H, ) -> Result<WriteResult, EngineError>

Same as crate::Engine::append but invokes hooks on each protocol phase.

Errors

Same as crate::Engine::append.

pub async fn delete_traced<H: EngineDeleteTraceHooks + ?Sized>( &self, world: &ValidatedWorldPath, metadata: DeleteMetadata, preconditions: Preconditions, tier: AccessTier, hooks: &H, ) -> Result<(), EngineError>

Same as crate::Engine::delete but invokes hooks on each protocol phase and records the supplied DeleteMetadata in the audit intent.

Adapters that want to surface the deleted representation’s content type and headers in operator audit views should use this method instead of crate::Engine::delete (which records empty metadata).

Errors

Same as crate::Engine::delete, plus the hook-side audit_intent_failed callback fires before the EngineError::Storage / EngineError::TransientStorage / EngineError::InsufficientStorage / EngineError::InternalInvariant result is returned when the audit-intent write itself fails.

Trait Implementations

impl Clone for Engine

fn clone(&self) -> Engine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Engine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.