Commit System¶

The commit system provides transactional persistence with history tracking.

When to use: Use CommitDatabase for versioned persistence with history, branching, and sync. Every change creates a commit, enabling undo/redo and concurrent editing.

Quick Start¶

from dsviper import CommitDatabase, CommitMutableState

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

# Create mutable state from latest commit
state = db.state(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 multiplayer editing where concurrent changes to different fields merge automatically.

from dsviper import CommitDatabase, 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 = db.state(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 cause one to be overwritten. With update(), edits to different fields merge automatically—essential for multiplayer editing.

Choosing the Right Class¶

Use Case	Class	Example
Open versioned database	`CommitDatabase`	`db = CommitDatabase.open(path)`
Read state at specific commit	`CommitState`	`state = db.state(commit_id)`
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.

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.

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.