Commit Engine

The Commit Engine is Viper’s versioned persistence layer. It turns a state described in DSM into an immutable, content-addressed DAG of commits — the substrate that makes time travel, undo/redo, multi-head exploration, and mechanical convergence between concurrent streams possible.

It is a Viper subsystem first and a Python API second. The Python exposure lives in dsviper (CommitDatabase, CommitMutableState, commit_mutations); Qt-side tools live in dsviper-tools and dsviper-components. The pages below document the engine itself — its guarantees, its modes of use, and the contract it asks of the application that consumes its output.

Place in the ecosystem

• Depends on — DSM (defines the shape of the data being committed) and the Viper C++ engine (see Naming).

• Consumed by — dsviper (Python exposure of the commit API), dsviper-tools (server, editors, dsm_util), dsviper-components (Qt Widgets and QML observers of a CommitStore), Commit Applications (all three are commit-based — see below).

• Distribution — no standalone package. The engine ships inside Viper and reaches Python through dsviper on PyPI.

Where it sits in the value chain

Without the Commit Engine, dsviper reads and writes against the plain Database backend — flat key-value, no history. The Commit Engine adds versioning: an immutable DAG, undo/redo, multi-head exploration, and deterministic convergence between concurrent streams. See Value Chains for the broader picture.

Tools that ship with the DevKit

Several DevKit artefacts operate directly on the Commit Engine:

• cdbe.py — Commit Database Editor (Qt Widgets).

• commit_database_server.py — network access + commit_admin.py.

• dsm_util.py create_commit_database — create a CommitDatabase from DSM.

• dsviper-components — Qt-side observers on the CommitStore notifier.

dbe.py is not in this list — it targets the non-versioned Database backend.

Commit Applications

For Commit Applications built on the engine (ge-py, ge-qml, web-cdbe), see Commit Applications.

Topics

• Commit Engine
  • Modes of Use
  • Opening a CommitDatabase
  • Reading State
  • Mutations
  • Complete Example
  • Path-Based Mutators
  • Commit History
  • Embedded Definitions
  • Safe Usage
• The Dual-Layer Contract
  • The Contract
  • Why the Engine’s Output Is Untrusted Data
  • Three Error Families
  • What Commit Provides
  • What Commit Does NOT Provide
  • Implications for dsviper Code
  • Summary
  • See Also

Status

Part of DevKit 1.2.x (LTS, feature-locked).