Skip to content
Back to top
View this page

# 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)

See also

For detailed examples and the Dual-Layer Contract, see Commit System.

## 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.