Commit Database¶

The Commit Database provides transactional persistence with history tracking. CommitDatabase is the persistence layer; two stateless namespaces operate over it, each taking a CommitDatabase as its first argument:

CommitStateBuilder — reconstruct a CommitState from a chosen commit: state(db, id), initial_state(db).
CommitDatabaseHelper — reduce heads and navigate: reduce_heads(db, anchor), forward / fast_forward.

(CommitDatabase itself answers topology queries — head_commit_ids, last_commit_id, is_ancestor — and holds no “current” state.) A CommitStore wraps the persistence layer and both namespaces behind a stateful facade (undo/redo, the dispatch surface) for interactive apps. For why a reconstructed state is a blind replay of the linearized trace, see Commit Database.

Quick Start¶

from dsviper import CommitDatabase, CommitStateBuilder, CommitMutableState

# Open commit database (created with dsm_util.py)
db = CommitDatabase.open("model.cdb")
db.definitions().inject()

# Create mutable state from latest commit
state = CommitStateBuilder.state(db, db.last_commit_id())
mutable = CommitMutableState(state)

# Apply mutations via AttachmentMutating interface
mutating = mutable.attachment_mutating()
mutating.set(MYAPP_A_USER, key, document)

# Commit changes → returns new commit ID
commit_id = db.commit_mutations("Add user", mutable)

Path-Based Mutations¶

Use Path with update() to modify specific fields without replacing the entire document. This enables disjoint concurrent writes — changes to different fields converge automatically.

from dsviper import CommitDatabase, CommitStateBuilder, CommitMutableState, Path

db = CommitDatabase.open("model.cdb")
db.definitions().inject()

# Build a path to a nested field: document.address.city
path_city = Path.from_field("address").field("city").const()

# Create mutable state
state = CommitStateBuilder.state(db, db.last_commit_id())
mutable = CommitMutableState(state)
mutating = mutable.attachment_mutating()

# Update only the city field (not the whole document)
mutating.update(MYAPP_A_USER, user_key, path_city, "Paris")

# Commit
db.commit_mutations("Update city", mutable)

With set(), concurrent edits to the same document silently lose one (last-writer-wins). With update(), edits to different fields converge without loss.

Supervised Reconciliation¶

Reconciling a merge — CommitMergeAnalyzer and friends — is an additive supervisor over this API, documented on its own page: Merge Reconciliation.

Database ↔ CommitDatabase Transfer¶

Moving content between the flat Database and the versioned CommitDatabase — convert, materialize, faithful copy, and flatten — is a set of converters documented on its own page: Database Transfer.

Choosing the Right Class¶

Use Case	Class	Example
Open commit database	`CommitDatabase`	`db = CommitDatabase.open(path)`
Read state at specific commit	`CommitStateBuilder`	`state = CommitStateBuilder.state(db, commit_id)`
Reduce divergent heads	`CommitDatabaseHelper`	`CommitDatabaseHelper.reduce_heads(db)`
Prepare mutations	`CommitMutableState`	`mutable = CommitMutableState(state)`
Read documents (get, keys, has)	`AttachmentGetting`	`getting = state.attachment_getting()`
Write documents (set, update)	`AttachmentMutating`	`mutating = mutable.attachment_mutating()`
Inspect commit metadata	`CommitHeader`	`header = db.commit_header(id)`

Core Classes¶

`dsviper.Commit`	A class used to represent a commit.
`dsviper.CommitDatabase`	A Commit database keeps the history of mutations in a DAG of commit.
`dsviper.CommitDatabaseSQLite`	A low-level class used to represent the database based on SQLite3 through the CommitDatabasing interface.
`dsviper.CommitDatabaseRemote`	A low-level class used to represent a remote Commit database through the CommitDatabasing interface.
`dsviper.CommitDatabaseServer`	A CommitDatabaseServer provide network access to a CommitDatabase.
`dsviper.CommitDatabasing`	An interface used to abstract the implementation of the persistence layer for a Commit database.

State Access¶

`dsviper.CommitState`	A class used to represent data at a specific commit.
`dsviper.CommitMutableState`	A class used to register the mutations of a value executed through the attachmentMutating interface.
`dsviper.CommitStateBuilder`	A utility class to build CommitState.

History & DAG¶

`dsviper.CommitNode`	A class used to represent a node in the commit DAG.
`dsviper.CommitNodeGrid`	A class used to represent the location of a commit node in the grid.
`dsviper.CommitNodeGridBuilder`	A class used to build the grid layout of the commit DAG.
`dsviper.CommitHeader`	A class used to represent the header of a commit.
`dsviper.CommitData`	A class used to represent data associated with a commit during the synchronization of two databases.
`dsviper.CommitEvalAction`	A class used by the evaluator to reconstruct a value by executing mutation opcodes.
`dsviper.CommitDatabaseHelper`	A utility class for a Commit Database.

Synchronization¶

`dsviper.CommitStore`	A high-level application class used to implement the store, dispatch, undo/redo and notification concepts inspired by the redux approach.
`dsviper.CommitStoreNotifying`	An interface used to represent the notification emitted by a store.
`dsviper.CommitSynchronizer`	A class used to synchronize two concrete databases through the CommitDatabasing interface (low-level driver interface).
`dsviper.CommitSynchronizerInfo`	A class used to represent data exchanged during the synchronization of two databases.
`dsviper.CommitSynchronizerInfoTransmit`	A class used to represent statistics of data exchanged during the synchronization of two databases.
`dsviper.CommitSyncData`	A class used to represent data exchanged during the synchronization of two databases.

Tracing¶

`dsviper.CommitStateTracing`	An interface used to trace a value (aka document).
`dsviper.CommitStateTrace`	A class used to represent traced opcode.
`dsviper.CommitStateTraceProgram`	A class used to represent traced opcode.
`dsviper.ValueProcessorTrace`	A class used to represent traced opcode.
`dsviper.ValueProcessorTraceOpcode`	A class used to represent a traced opcode.