Commit Engine Overview¶

The Commit Engine provides DAG versioning with immutable history, enabling transactional persistence, undo/redo, and distributed synchronization.

Positioning¶

Aspect	Viper Runtime	Commit Engine
Status	Core product	Specialized
Files	~570 .hpp	64 .hpp
Philosophy	Proactive	Best-effort
Exceptions	Raised immediately	Recovered (protected mode)
Validation	Immediate rejection	Deterministic No-Op
Scope	Structural + Semantic	Structural only

The Viper Runtime is complete and standalone. The Commit Engine adds versioning capabilities and delegates semantic validation to the application layer.

Architecture¶

+----------------------------------------------------------+
|                      Commit Engine                       |
|                  (built on Viper Runtime)                |
|                                                          |
|  * DAG versioning with immutable history                 |
|  * Best-effort evaluation                                |
|  * Content-addressable commits (SHA-1)                   |
|  * 64 .hpp files                                         |
+----------------------------------------------------------+
                        | built on
+==========================================================+
|                   Viper Runtime                          |
|          Type/Value/Codec/Database/RPC...                |
|                 (20 domains, proactive)                  |
+==========================================================+

Key Classes¶

Class	Responsibility
`Commit`	Immutable structure: header + program
`CommitId`	SHA-1 identifier (20 bytes), content-addressable
`CommitHeader`	Metadata: commitId, parentCommitId, timestamp, label
`ValueProgram`	Indexed collection of ValueOpcode by key
`CommitState`	Readonly state at a specific commitId
`CommitMutableState`	Mutable state for building mutations
`CommitDatabase`	High-level facade managing commits, blobs, DAG
`CommitDatabasing`	Backend interface (SQLite, Remote)
`CommitStore`	State management with undo/redo (Redux-inspired)
`CommitSynchronizer`	Synchronization between databases

Commit Types¶

CommitType	Description
`Mutations`	Normal commit containing ValueProgram
`Disable`	Evaluates target commit’s opcodes in ignore mode (XArray tombstoning, other opcodes become no-ops)
`Enable`	Re-evaluates target commit’s opcodes in execute mode (restores normal evaluation)
`Merge`	Combines concurrent streams by creating merge commit (state via DAG linearization + evaluation)

Content-Addressable Commits¶

Each commit is identified by the SHA-1 hash of its serialized header:

CommitId = SHA-1(header blob)

This ensures:

Identical content produces identical IDs
History cannot be tampered with
Distributed systems can verify integrity

Philosophy: Best-Effort¶

The Commit Engine operates in best-effort mode, contrasting with Viper’s proactive philosophy:

void execute(opcode, result) {
    try {
        // Execute the opcode
    } catch (...) {}  // Exceptions recovered (protected mode)
}

The system always completes. Mutations targeting non-existent elements become Deterministic No-Ops (same as Google Docs, Figma).

The catch(...){} is a necessary consequence of DAG linearization (similar to OT evaluation of operations on deleted elements): opcodes may target documents that don’t exist (Document_Set disabled) or unresolved paths. See The Dual-Layer Contract for implications.

Interactions with Viper Runtime¶

Domain	Relation	Via
Value System (04)	Uses	`Value`, `ValueKey`, `ValueSet`
Path System (06)	Uses	`Path` - navigation in structures
Blob System (08)	Uses	`Blob`, `BlobId` - serialization
Attachment System (11)	Uses	`Attachment` - key scope
Hashing System (15)	Uses	SHA-1 for CommitId
Stream/Codec (14)	Uses	`StreamCodecInstancing`
RPC System (17)	Uses	`CommitDatabaseRemote`

Typical Flow¶

Mutation:  CommitMutableState::set/update -> accumulates ValueProgram
Commit:    CommitDatabase::commitMutations() -> serialize -> compute CommitId -> store
Reading:   CommitDatabase::state(commitId) -> DAG traversal -> CommitState (cached)
Undo:      disableCommit() -> new Disable commit -> CommitUndoStack::undo()
Sync:      CommitSynchronizer::sync() -> compare -> incremental transfer