Crate obj_core 

obj-core — internal storage engine for the obj embedded document database.

⚠️ UNSTABLE — not a stable public API

obj-core is an implementation detail of obj-db. It is published to crates.io only because obj-db depends on it; its public API carries no SemVer guarantee and may change in any release, including patch releases. Do not depend on obj-core directly — depend on obj-db and use the obj crate’s API. Only obj-db’s public surface is frozen at 1.0 (see docs/public-api.md); obj-core is deliberately excluded from the public-api freeze gate so the engine can evolve freely.

This crate hosts the layered storage engine: the platform syscall wrappers (L0), the pager (L1), the WAL (L2), the B-tree (L3), the document codec (L4), the catalog (L5), and the transaction manager (L7). Layers are built bottom-up across milestones; see the project plan and power-of-ten.md for the design discipline this crate must uphold.

On-disk format

The .obj file format that this crate reads and writes is specified in docs/format.md at the repository root. That document is the authoritative description of the page-0 file header, the per-page CRC32C trailer scheme, and the page-type tag enumeration; this crate is its reference implementation.

unsafe policy

This crate does not carry a crate-level #![forbid(unsafe_code)] because the platform submodule holds the project’s syscall wrappers. Every other submodule should be safe; new submodules SHOULD include #![forbid(unsafe_code)] of their own where appropriate.

Re-exports

pub use crate::catalog::Catalog;

pub use crate::catalog::CollectionDescriptor;

pub use crate::catalog::IndexDescriptor;

pub use crate::catalog::IndexStatus;

pub use crate::codec::Document;

pub use crate::error::Error;

pub use crate::error::LockKind;

pub use crate::error::Result;

pub use crate::id::Id;

pub use crate::index::IndexKind;

pub use crate::index::IndexSpec;

pub use crate::integrity::IntegrityFailure;

pub use crate::integrity::IntegrityReport;

pub use crate::pager::CompressionMode;

pub use crate::pager::PageHandle;

pub use crate::pager::ReaderSnapshot;

pub use crate::pager::SnapshotId;

pub use crate::platform::FileBackend;

pub use crate::platform::SyncMode;

pub use crate::txn::ReadTxn;

pub use crate::txn::TxnEnv;

pub use crate::txn::WriteTxn;

pub use crate::txn::DEFAULT_BUSY_TIMEOUT;

pub use crate::wal::Lsn;

Modules

backup

Hot backup primitives (M11 #92).

btree

B+tree (L3) — copy-on-write B+tree over the pager.

catalog

Catalog (L5) — on-disk registry of collections.

codec

Document codec (L4) — per-document header + postcard payload.

error

Crate-level error type.

id

Per-collection document identifier — Id(NonZeroU64).

index

Secondary indexes (L6) — index B+trees layered over the M4 B+tree.

integrity

On-disk integrity check (M11 #90).

pager

Pager (L1) — fixed-size page allocator, freelist, bounded LRU cache, and the WAL-aware write path.

platform

Platform layer (L0).

txn

Transaction layer (L7).

wal

Write-ahead log (L2).