Viper's subsystem for the mutation DAG — versioned history, undo/redo, time travel.
Commit is structured as three layers, from the disk upward. Each has a precise role; together they form the substrate of every Commit Application.
the persistence layer
the runtime surface — holds the current state
CommitDatabasethe application pattern
CommitStore with
typed code generated by Kibo from
your DSM and domain logic
Without the Commit Database, reads and writes go against the plain
Database backend — flat key-value, no history.
The Commit Database adds versioning on top : an immutable mutation DAG with
deterministic reduction. The CommitStore adds the runtime
surface (dispatch, undo, notifications). The Commit Application Model is
how a real application composes them together.
Same Model, two realities. Python collapses one layer because there is no language boundary to cross.
6 layers — function pools cross to Python
5 layers — no boundary, no pools
The differentiator is the Bridge Layer. In C++, generated function pools (held by the Context) and hand-written pool bridges expose typed business code to Python scripting. In Python, the dispatch lambda calls business functions directly — same layer, no pool.
Raptor Editor is the example par excellence of this model : two completely independent native UI shells — an AppKit shell on macOS (~6,100 lines) and a UIKit shell on iPadOS (~5,500 lines) — over the same bridges, the same business logic, the same generated data classes, the same Viper C++ runtime. Each shell is roughly 3 % of the project ; the second one cost as much as the first, with no shared code between them. Adding a Service is one more layer-1 surface on that same core, not a second code base.
Two independent axes : the operations are always available ; the context decides whether the engine has anything to pick between. The Dual-Layer Contract applies along the context axis, not the operation axis.
What you can do — operation axis, always available
read-only
Pick any past commit and read the world as it was at that point. Determinism, immutability, content addressing — the same state, every time.
append-only
Step back along the chain, diverge, redo. Implemented by appending an Enable / Disable commit that masks a target — never rewriting history.
parallel heads
Diverge the DAG and keep parallel heads alive ; merge them back on your own schedule.
Where you do it — context axis, decides whether the Contract applies
one author at a time
Linear history. Every read returns exactly what you wrote — nothing for the engine to pick between. The Contract stays on the shelf.
scope-decomposed cooperation
Concurrent writers operate on structurally disjoint targets ; the engine still has nothing to pick between — every intent survives intact. The Contract is reference material.
uniqueness, referential integrity, regulated domains
Concurrent writers may collide on overlapping paths. The engine picks deterministically but cannot preserve every intent. This is where the Contract is load-bearing — exit by re-architecting upstream toward disjoint scope, or by supervising reduction.
Operations × context : doing an undo in single-stream is trivial. The same undo in multi-stream reads through a state produced by an earlier reduction — the read crosses an import boundary. The Modes of Use diagnostic names this distinction.
A CommitDatabase is a SQLite file. Multiple processes on the same machine open it directly through SQLite's own concurrent access — no server needed. The two patterns below address the cross-site case : how a CommitDatabase reaches more than one machine.
remote, no local copy
A thin RPC proxy talks to a server that holds the SQLite file. The application calls a CommitDatabase the same way as a local file ; it does not know whether the file is on this machine or behind a network hop.
Useful for centralised editing of a single shared database.
local copy + periodic sync
Each site holds its own local CommitDatabase ; a synchroniser copies commits between any two instances (local↔local, local↔remote, remote↔remote).
Offline work, local-first reads, bandwidth amortisation.
Each site has its own write head, so a replicated topology is multi-stream by construction — the diagnostic above applies.
Sync copies commits ; it does not merge them. After sync, both sides hold the union of commits — including any divergent heads. Reducing them to a single head is a separate step, left to the application. Read the sync chapter ↗
When invariants are strong — uniqueness, referential integrity, regulated domains — the Commit Database is deliberately domain-agnostic. It never refuses to reduce ; it picks a deterministic outcome and moves on. Validation moves to the application, at read time, not at write time.
CommitId = SHA-1(content), tamper-evident.“I guarantee structural integrity. I hand you back data that is structurally sound but semantically untrusted. You re-validate it on read.”
— The Dual-Layer Contract
Shipped with DevKit is cdbe.py, a generic editor without a domain.
The other three are illustrative walk-throughs — each wires the
full chain in real code, on a different presentation tier (Qt Widgets, Qt Quick /
QML, server-rendered HTML/CSS), to show how the pieces fit together.
Opens any CommitDatabase through the dynamic API and exposes the
full mutation DAG : history, undo/redo, synchronisation with a remote server,
embedded Python scripting. A minimal Application Context without a domain —
the working tool, not a walk-through.
PySide6 desktop application demonstrating dsviper end-to-end with a graph database
visualization. Built on dsviper-components (Qt Widgets).
QML port of ge-py, built on dsviper-components-qml (Qt Quick). Same
value chain, same business logic, same CommitStore facade — the UI is QML
driven by Python QObject models registered as QML context properties.
Third presentation-tier instance — Flask + HTML5, no JavaScript. Same dsviper foundation as cdbe, surfaced through a server-rendered web UI instead of a Qt one. Illustrates that the chain is not bound to a specific UI toolkit.