Viper Philosophy

This document explains the fundamental design principles that govern Viper Runtime.

What is Viper?

Viper is a metadata-driven runtime (v1.2.0 LTS) that simplifies C++/Python interoperability through a unified type and value system. It is not a language, framework, or library—it is a complete system for managing structured data.

Viper as a Data Runtime

Like the JVM runs Java bytecode, Viper runs typed values:

Capability

Implementation

Dynamic type system

33 TypeCodes with runtime metadata

Strong typing

Immediate exceptions on type mismatch

Auto serialization

Binary/JSON codecs via TypeCode dispatch

Memory management

std::shared_ptr with reference counting

Cross-language

Same types in C++ and Python

Viper as a Mini-OS for Data

Viper provides OS-like services for data instead of processes:

OS Concept

Viper Equivalent

File System

Database (SQLite-backed)

Memory

Blob storage (content-addressed)

Process State

CommitState (immutable snapshots)

Transactions

begin/commit/rollback

IPC

RPC (remote procedure calls)

Version Control

Commit DAG (like Git for data)

Principle 0: Think Before You Code

“Avant donc que d’écrire, apprenez à penser.” — Boileau

Solve the problem completely at the right architectural level. Do not delegate complexity upward unless the upper layer has domain knowledge you lack.

This principle guides all Viper design decisions and ensures problems are solved where they belong.

Metadata Everywhere

Runtime type metadata drives serialization, validation, RPC, Python binding, and persistence. Every Viper Value object knows its type and can describe itself.

Mechanism

Purpose

TypeCode

Enum (33 codes) enabling fast polymorphic dispatch

RuntimeId

MD5 hash guaranteeing C++/Python compatibility

Definitions

Central registry providing runtime reflection

representation()

Self-describing string format for each Type and Value

Implications

  1. No manual serialization code - Codecs use TypeCode dispatch to serialize any Value

  2. No manual type checking - TypeChecker validates via metadata automatically

  3. RPC protocol self-describing - Definitions transmitted with calls

Commit Immutability

The Commit system combines mutability during construction with immutability after persistence.

Phase

State

Mutability

Purpose

Construction

CommitMutableState

Mutable

Build/modify data freely

Persistence

CommitState

Immutable

Historical snapshot in the DAG

Benefits

  • Thread safety: Committed states are immutable—no locks needed for read access

  • Multiplayer editing: Each client has isolated CommitMutableState, converge at commit

  • Undo/redo: Navigate the commit DAG (history is immutable)

  • Caching: Committed values can be cached indefinitely

Reference Semantics

Viper uses reference semantics (like Python) rather than value semantics (like C++ STL). Assignment and parameter passing share the underlying data rather than copying.

C++ STL (Value Semantics)

Viper (Reference Semantics)

vector<int> a = b; copies

shared_ptr<ValueVector> a = b; shares

Parameter copy by default

Parameter shared by default

Explicit std::move for moves

Explicit copy() for deep copy

Implications

  1. Python-like behavior - Natural for Python binding

  2. Efficient by default - No accidental copies

  3. Explicit when needed - Value::copy() for deep copy

Proactive Philosophy

Viper Runtime follows a proactive philosophy: invalid operations raise exceptions immediately.

// Viper raises immediately on type mismatch
auto vec = ValueVector::make(TypeVector::make(TypeInt32::Instance()));
vec->append(ValueString::make("hello"));  // throws: expected Int32, got String

This contrasts with permissive approaches where errors may pass silently. Viper ensures:

  • Type errors caught immediately

  • Invalid paths rejected at call time

  • No silent data corruption

Note: The Commit Engine operates differently—in best-effort mode, mutations targeting non-existent documents or unresolved paths are silently ignored (catch(...){}). See Commit Overview.

The Viper Paradox

Viper is a dynamic runtime (like Python) that is strongly typed (unlike Python).

Aspect

Python

Viper

Type checking

Runtime, permissive

Runtime, immediate exceptions

Type errors

May pass silently

Always throws immediately

Type metadata

Limited (type())

Complete (TypeCode, RuntimeId, etc.)

Serialization

Manual (pickle, json)

Automatic via metadata

The best of both worlds: Viper combines the flexibility of dynamic typing with the safety guarantees of static typing.

See Also