Struct FieldStore 

pub struct FieldStore { /* private fields */ }

Implementations

impl FieldStore

pub fn open(root: impl AsRef<Path>) -> Result<Self>

Create or open a field store rooted at root (the filesystem backend).

pub fn open_packed(root: impl AsRef<Path>) -> Result<Self>

Create or open a field store whose seed namespace is a packed segment store (fieldpack/) instead of one file per node.

The descriptor, manifest, hierarchical index, and cache namespaces remain plain files, so the seek-based partial-descriptor lane and FieldId are unchanged; only <root>/seed is replaced by <root>/fieldpack. A packed store must therefore be opened with the matching CLI flag (--packed), exactly like --entropyfs.

pub fn open_packed_with_policy( root: impl AsRef<Path>, policy: SyncPolicy, ) -> Result<Self>

Like FieldStore::open_packed, but with an explicit packed-store durability SyncPolicy. The default is SyncPolicy::Batch; SyncPolicy::Each restores one sync per seed node. The policy is irrelevant for the other backends and ignored by them.

pub fn io(&self) -> &IoCounters

The physical-I/O counters shared by this store and its seed substrate.

Every descriptor/manifest/index/seed read made through any handle derived from this store is attributed here; an observation snapshots it before and after to report its own physical bytes (review fix #1).

pub fn root(&self) -> &Path

The store root directory.

pub fn seeds(&self) -> &dyn SeedStore

The seed store (for advanced callers and courts).

pub fn seeds_mut(&mut self) -> &mut dyn SeedStore

Mutable seed store access.

pub fn cache(&self) -> Result<DerivedCache>

Open the disposable derived observation cache (11.8) under this store.

The cache is never normative: it can always be deleted and observations remain correct by recomputation (ADR-0027).

pub fn set_promote(&mut self, policy: PromotePolicy)

Set the opt-in durable promotion policy (Phase 15.6). The default is promote::PromotePolicy::default (disabled), so every existing path is byte-identical until a caller explicitly enables it.

pub fn promote_policy(&self) -> PromotePolicy

The active promotion policy (disabled by default).

pub fn promoted(&self) -> Result<PromotedStore>

Open the durable promoted store (Phase 15.6) under this store’s promoted/ directory. Never normative and never consulted by materialize --exact.

pub fn sync(&self) -> Result<()>

Make every acknowledged write power-durable before the handle is dropped.

The EntropyFS engine acks a put_blob at rename but does not barrier, so a fresh open in another process can miss an unpublishied epoch. Calling this after a mutation closes that gap. The filesystem backend writes atomically (tmp -> fsync -> rename) and needs no barrier.

pub fn put_descriptor(&mut self, bytes: &[u8]) -> Result<Id>

Store a serialized .voldoc descriptor as a content-addressed blob.

Returns the blob’s Id (BLAKE3-256(bytes)), which is what the field manifest binds. Idempotent.

pub fn get_descriptor(&self, id: &Id) -> Result<Vec<u8>>

Fetch a descriptor blob, verifying its content id.

pub fn put_field(&mut self, manifest: &FieldRoot) -> Result<FieldId>

Store a canonical field manifest.

Durability ordering: a published manifest must never reference seed bytes that are not yet on stable storage. The packed substrate batches its per-node syncs (SyncPolicy::Batch), so barrier the open segment before publishing. This is a no-op for the filesystem and EntropyFS substrates (which make each node durable in put_node).

pub fn get_field(&self, id: &FieldId) -> Result<FieldRoot>

Fetch a field manifest, verifying its content id and universe.

pub fn list_fields(&self) -> Result<Vec<FieldId>>

List every stored field manifest id.

The filesystem backend reads the field/ directory. The EntropyFS backend declines with UnsupportedFeature: the engine exposes no per-blob enumeration, so a manifest cannot be listed — but any manifest remains openable by its FieldId (get_field).

pub fn put_external_context( &self, id: &FieldId, ctx: &ExternalContext, ) -> Result<()>

Attach (or replace) an external::ExternalContext beside a field.

The record is written atomically into the external/ namespace. This is not an exactness-path write: it never touches the descriptor, the seed DAG, the index, the cache, or the manifest, and a field with no context is still fully exact.

pub fn get_external_context( &self, id: &FieldId, ) -> Result<Option<ExternalContext>>

Read the attached external::ExternalContext, or None when none is attached. A malformed record fails closed rather than answering.

pub fn clear_external_context(&self, id: &FieldId) -> Result<bool>

Remove the attached external context. Returns whether one was present. Removing it restores the pre-attach state exactly: the field’s document-derived observations and exact materialization are untouched.

pub fn ingest( &mut self, descriptor_bytes: &[u8], limits: Limits, ) -> Result<FieldId>

Ingest a serialized .voldoc descriptor as a new field.

Stage A (durable exact capture): store the descriptor blob and an exact DocumentExact root node, then write the manifest. Deeper Stage-B procedural nodes are added by crate::field::ingest.

pub fn ingest_verified( &mut self, descriptor_bytes: &[u8], source: &[u8], limits: Limits, ) -> Result<FieldId>

Ingest a descriptor, verifying it materializes to a caller-supplied source.

Identical to FieldStore::ingest except the materialized source is byte-compared to source instead of being dropped. A direct build (field-build) already holds the exact source and proved materialize(descriptor) == source in the encode court; passing the original bytes here keeps that one non-negotiable check (length + byte equality, hence SHA-256) while letting the caller scan the source rather than a freshly materialized copy. The authority stored is unchanged.

Trait Implementations

impl Debug for FieldStore

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

Formats the value using the given formatter.