Struct WriteTransaction 

pub struct WriteTransaction<'db> { /* private fields */ }

Single writer transaction.

Mutations accumulate into a private write overlay layered over the parent snapshot; reads fall through the overlay then the base. commit appends the overlay’s mutation log to the WAL (when dirty) and publishes a fresh snapshot; rollback drops the overlay and appends nothing.

Performance

Creating and moving a writer is O(1); each mutation is O(log change).

Implementations

impl WriteTransaction<'_>

pub fn register_role( &mut self, name: impl Into<String>, ) -> Result<RoleId, DbError>

Registers a structural incidence role.

Errors

Returns DbError when the name already exists or ID allocation fails.

Performance

This method is O(log role count + name length).

pub fn register_label( &mut self, name: impl Into<String>, ) -> Result<LabelId, DbError>

Registers an element or relation label.

Errors

Returns DbError when the name already exists or ID allocation fails.

Performance

This method is O(log label count + name length).

pub fn register_relation_type( &mut self, name: impl Into<String>, ) -> Result<RelationTypeId, DbError>

Registers a relation type.

Errors

Returns DbError when the name already exists or ID allocation fails.

Performance

This method is O(log relation type count + name length).

pub fn register_property_key( &mut self, name: impl Into<String>, family: PropertyFamily, value_type: PropertyType, ) -> Result<PropertyKeyId, DbError>

Registers a typed property key.

Errors

Returns DbError when the name already exists or ID allocation fails.

Performance

This method is O(log property key count + name length).

pub fn define_projection( &mut self, definition: ProjectionDefinition, ) -> Result<ProjectionId, DbError>

Defines a physical projection.

Errors

Returns DbError when referenced catalog IDs are unknown, the projection name already exists, or ID allocation fails.

Performance

This method is O(definition size + catalog lookup cost).

pub fn define_index( &mut self, name: impl Into<String>, definition: IndexDefinition, ) -> Result<IndexId, DbError>

Defines an index.

Errors

Returns DbError when referenced catalog IDs are unknown, the index name already exists, or ID allocation fails.

Performance

This method is O(definition size + catalog lookup cost).

pub fn create_element(&mut self) -> Result<ElementId, DbError>

Creates a canonical element.

Errors

Returns DbError::IdOverflow when element IDs are exhausted.

Performance

This method is O(log element change).

pub fn create_relation(&mut self) -> Result<RelationId, DbError>

Creates a canonical relation.

Errors

Returns DbError::IdOverflow when relation IDs are exhausted.

Performance

This method is O(log relation change).

pub fn create_incidence( &mut self, relation: RelationId, element: ElementId, role: RoleId, ) -> Result<IncidenceId, DbError>

Creates a canonical incidence.

Errors

Returns DbError when referenced IDs are unknown or incidence IDs are exhausted.

Performance

This method is O(log incidence change + reference lookup cost).

pub fn tombstone_element(&mut self, id: ElementId) -> Result<(), DbError>

Tombstones a canonical element and its incidences.

Errors

Returns DbError::UnknownElement when the element is not visible.

Performance

This method is O(incidence count).

pub fn tombstone_relation(&mut self, id: RelationId) -> Result<(), DbError>

Tombstones a canonical relation and its incidences.

Errors

Returns DbError::UnknownRelation when the relation is not visible.

Performance

This method is O(incidence count).

pub fn tombstone_incidence(&mut self, id: IncidenceId) -> Result<(), DbError>

Tombstones a canonical incidence.

Errors

Returns DbError::UnknownIncidence when the incidence is not visible.

Performance

This method is O(log incidence change).

pub fn add_element_label( &mut self, element: ElementId, label: LabelId, ) -> Result<(), DbError>

Adds a label to an element.

Errors

Returns DbError when the element or label is unknown.

Performance

This method is O(log element change + log label count).

pub fn add_relation_label( &mut self, relation: RelationId, label: LabelId, ) -> Result<(), DbError>

Adds a label to a relation.

Errors

Returns DbError when the relation or label is unknown.

Performance

This method is O(log relation change + log label count).

pub fn set_relation_type( &mut self, relation: RelationId, relation_type: RelationTypeId, ) -> Result<(), DbError>

Sets a relation type.

Errors

Returns DbError when the relation or relation type is unknown.

Performance

This method is O(log relation change + log relation type count).

pub fn set_property( &mut self, subject: PropertySubject, key: PropertyKeyId, value: PropertyValue, ) -> Result<(), DbError>

Sets a property value.

Errors

Returns DbError when the subject or key is unknown, or the value does not match the key schema.

Performance

This method is O(log subject change + log key count).

pub fn remove_property( &mut self, subject: PropertySubject, key: PropertyKeyId, ) -> Result<(), DbError>

Removes a property value.

Errors

Returns DbError when the subject or key is unknown.

Performance

This method is O(log subject change + log key count).

pub fn commit(self) -> Result<CommitSeq, DbError>

Commits this write transaction durably.

A non-dirty commit returns the parent’s commit sequence without appending to the WAL or publishing. A dirty commit encodes the overlay’s mutation log into one WAL frame (with the watermark op last), appends it with an fsync (truncating back to the captured EOF on any write error so no interior torn record survives), THEN folds the delta into a fresh Arc<Overlay> and publishes a new Arc<Snapshot>.

After publishing, a dirty commit consults the configured CheckpointPolicy: it releases the writer lock FIRST (so the fold can re-acquire it), then folds when the delta-log has outgrown the base. The committed frame is already durable, so an auto-fold failure does not lose data; it is surfaced to the caller.

Errors

Returns DbError when commit-sequence allocation, frame encoding, the durable append, or a triggered auto-checkpoint fold fails.

Performance

This method is O(change) for the dirty path — flat as the base grows. The publish step shares the parent snapshot’s already-materialized [crate::overlay::BaseRecords] and derived index by Arc (a commit never folds, so the base is byte-identical within the generation), so it neither re-decodes the base nor rebuilds the index. A triggered fold adds O(visible state bytes) on top.

pub fn rollback(self)

Drops this write transaction without committing.

Performance

This method is O(1) excluding staged-delta drop cost.