vprevail
Distributed System Prevalence, 16-Shard CoW MVCC & Durable Virtual Objects

vprevail — Distributed System Prevalence, 16-Shard CoW MVCC & Durable Execution Engine

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

vprevail is a zero-dependency distributed in-memory database, 16-shard Copy-on-Write (CoW) Multi-Version Concurrency Control (MVCC) engine, Restate-style Durable Execution & Virtual Object runtime, and Role-Separated Web Control Plane. Built on the System Prevalence architectural lineage (Klaus Wuestefeld's Prevayler, LMAX Disruptor, Redis/VoltDB, and TigerBeetle), vprevail keeps the entire active dataset in RAM for wait-free nanosecond reads while persisting every mutation sequentially inside an IEEE 802.3 CRC32-verified Write-Ahead Log (.log), 24-byte sparse index (.idx), and non-blocking point-in-time snapshot archive (.snap).


Dual-Persona Overview

For Application Developers & Quant / Platform Engineers

  • Wait-Free Multi-Model MVCC StateSpace: Store dynamic integers, floats, strings, ordered tuples, nested maps, and strongly-typed structured records across isolated logical namespaces without defining boilerplate root graphs.
  • Sub-Microsecond Reads & Instant Time-Travel: Readers check out immutable StateView snapshots in ~20 nanoseconds with zero mutex contention against writers, and query historical state by either logical CommitLog offset or nanosecond Hybrid Logical Clock (HLC) timestamp.
  • Unified State + Durable Workflows: Execute deterministic multi-key transactions (TxBatch), memoized durable workflow steps, non-blocking durable timers, external webhook Awakeable promises, and LIFO Saga compensations inside the exact same atomic CommitLog—eliminating dual-write drift between external workflow orchestrators and databases.
  • Polyglot HTTP/1.1 & SDK Ecosystem: Integrate from any language over /v1/* JSON REST & Server-Sent Events (SSE), or author deterministic durable workflows using the Python, TypeScript/Node.js, Go, and Rust SDKs.

For Site Reliability Engineers, Security Officers & Administrators

  • Self-Healing Crash Recovery & End-to-End CRC32 Integrity: Every storage and replication frame carries a 32-byte VPRV binary header with IEEE CRC32 checksums. Cold startup automatically detects and truncates power-loss torn tail writes while flagging mid-log bit-rot corruption.
  • Online Streaming Telemetry & Counterfactual Replay: Built-in O(1) Welford RunningStats (online Z-scores), 64-register HyperLogLog, BoundedRing buffers, Shannon entropy analyzers, and zero-copy Ephemeral Sandbox WAL Replay let operators backtest risk or SIEM rules against production history without touching live state.
  • Zero-Trust Security & Split-Brain Fencing: Enforces 256-byte padded constant-time bearer/cluster authentication, NIST SP 800-38D AES-256-GCM encryption at rest for workflow SubjectContext identities (with automatic bearer token stripping), and WAL-backed monotonic __system_fencing tokens across shard and Virtual Object migrations.

Role-Separated Web Control Plane Tour (HiDPI Daylight Captures)

vprevail ships a built-in HTTP/1.1 Web Control Plane separated into four role-scoped workspaces (/ui/auth, /ui/portal, /ui/delegated, and /ui/admin).

1. Authentication, Scope Provisioning & QR Pairing Gate (/ui/auth)

Principals authenticate with cluster credentials, request scoped workspace onboarding, or pair mobile/CLI sessions using pure vector ISO/IEC 18004 QR codes.

Authentication and Onboarding Gate

2. Self-Service MVCC Namespace & Time-Travel Studio (/ui/portal)

Authenticated users read, write, expire (TTL), and time-travel across their isolated self:<principal> namespace with {tag} partition-affinity keys.

Portal MVCC Key-Value and Time-Travel Studio

3. Delegated Durable Workflows & Awakeable Approvals (/ui/delegated)

Compliance officers and risk supervisors inspect suspended durable workflows, verify required RBAC roles (compliance:approve), resolve external Awakeable promises, and advance durable timers.

Delegated Durable Workflows and Awakeable Resolution

4. Global Admin Engine, 16-Shard MVCC & Cluster Telemetry (/ui/admin)

Cluster administrators monitor MVCC epochs, CommitLog offsets, monotonic HLC timestamps, 16-shard partition occupancy, fencing terms, and deterministic command execution.

Admin Cluster, MVCC Shards, and WAL Telemetry

5. Ephemeral Sandbox WAL Replay & Version Diff Inspector (/ui/delegated)

Operators fork an isolated zero-copy StateSpace across any historical [from_offset..to_offset] window, measuring microsecond replay latency and inspecting exact key-level state diffs.

Ephemeral Sandbox Replay and Time-Travel Version Inspector

6. Interactive Reference Application Studios (/ui/portal)

Run and audit PrevailBank (double-entry core banking ledger), PrevailAgent (AI agent sandbox with O(1) time-travel undo), PrevailExchange (price-time priority limit order book), and PrevailTwin (Live-to-Sim quant digital twin) directly in the browser.

Reference Application Studios and Double-Entry Ledger


60-Second Quickstart

1. Launch the Control Plane & HTTP/1.1 Gateway

BASH
# Start vprevail on 127.0.0.1:8080 with persistent WAL storage in ./data/prod
./vprevail serve --addr 127.0.0.1:8080 --data-dir ./data/prod --node-id prevail-node-1

Open http://127.0.0.1:8080/ui/auth in your browser to sign into the Self-Service Portal, Delegated Operations Workspace, or Global Administrator Console.

2. Write & Time-Travel Query via REST

BASH
# Mint an authenticated session token
curl -s -X POST http://127.0.0.1:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"principal_id":"admin:root","role":"admin","tenant_id":"tenant:global"}'

# Commit an atomic multi-key TxBatch across namespaces
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "tx-quickstart-01",
    "namespaces": ["wallets", "orders"],
    "keys": ["{acct-1}:usd", "{acct-1}:ord-1001"],
    "deleted": [0, 0],
    "values_json": ["{\"balance_cents\":250000}", "{\"sku\":\"nvme-4tb\",\"qty\":2}"]
  }'

3. Verify On-Disk WAL Integrity & Run Benchmarks

BASH
# Verify IEEE CRC32 checksums across all .log segments, .idx indexes, and .snap files
./vprevail inspect ./data/prod

# Run the quick verification benchmark suite (35 subsystem & reference app workloads)
./vprevail bench --quick

Suite Navigation Guide

Guide Audience Key Topics Covered
How-To Guide Developers Copy-pasteable recipes for REST CRUD, {tag} range scans, time-travel queries, durable workflows, Awakeables, and Python/TS/Go/Rust SDKs.
End-User Guide Portal Users Step-by-step walkthrough of /ui/auth, QR pairing, personal MVCC state, workflow invocations, CDC event streams, and Reference Studios.
Administrator Guide Operators & SREs 16-shard MVCC governance, streaming sketches, sandbox replay, .snap compaction, TCP replication, split-brain fencing, and Zero-Trust TLS/WireGuard.
Operations & Use Cases Architects & SREs Day-2 runbooks, IR-01..IR-05 incident playbooks, and complete guides for PrevailBank, PrevailAgent, PrevailExchange, PrevailTwin, and PulseLedger.
Configuration & CLI Reference All Personas Complete vprevail CLI flags, JSON/TOML runtime configuration schemas, environment variables, and /v1/* + /api/v1/* REST API payloads.
Performance & Sizing Capacity Planners 35-workload empirical benchmarks, Flush Mode durability matrix, RAM sizing formulas, and AWS / GCP / Azure / Hetzner / Bare-Metal projections.
Master User Handbook Offline Readers Consolidated single-volume compilation of all seven End-User, Administrator, and Operations guides.

vprevail — Developer & Operator How-To Guide

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This How-To Guide provides practical, copy-pasteable external recipes for integrating applications and automation pipelines with vprevail via the standalone CLI, the /v1/* HTTP/1.1 JSON & SSE Gateway, and the polyglot durable execution SDKs (Python, TypeScript/Node.js, Go, and Rust).


1. Starting vprevail in Development vs. Production Durability Mode

Fast Buffered Mode (Low-Latency Development & Replicated Clusters)

By default, vprevail appends 32-byte CRC32-framed records sequentially to the OS page cache without blocking every single mutation on a physical disk flush (sync_on_write = false):

BASH
./vprevail serve \
  --addr 127.0.0.1:8080 \
  --data-dir ./data/dev_node \
  --node-id dev-node-1

Strict Per-Commit fsync Mode (--sync + Static Bearer Token)

For single-node financial ledgers requiring strict RPO = 0 survival across sudden host power loss and Zero-Trust API perimeter enforcement, pass --sync and --auth-token:

BASH
./vprevail serve \
  --addr 127.0.0.1:8080 \
  --data-dir ./data/primary \
  --node-id prod-ny4-primary \
  --auth-token "vprv-prod-bearer-9f8e7d6c5b4a3210" \
  --sync

2. Reading, Writing & Expiring Keys with {tag} Partition Affinity

vprevail partitions every namespace across 16 Copy-on-Write shards. Prefixing related keys with {tag} (for example {cust:1001}:profile and {cust:1001}:wallet) routes them to the exact same FNV-1a shard so multi-key writes clone only 1/16th of the namespace and range scans inspect a single shard.

Put a Key with Optional Nanosecond TTL

BASH
# Store a permanent record (ttl_ns = 0)
curl -s -X POST http://127.0.0.1:8080/v1/state/put \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "value_json": "{\"owner\":\"Alice Rivera\",\"balance_cents\":150000,\"tier\":\"PRIME\"}",
    "ttl_ns": 0
  }'

# Store an ephemeral fraud-cooldown lock that expires deterministically after 5 minutes (300e9 ns)
curl -s -X POST http://127.0.0.1:8080/v1/state/put \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "session_locks",
    "key": "{cust:1001}:wire_cooldown",
    "value_json": "{\"locked\":true,\"reason\":\"new_beneficiary\"}",
    "ttl_ns": 300000000000
  }'

Point Lookup & Sorted Prefix / Range Scans

BASH
# Latest wait-free point lookup
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd"
  }'

# Co-located {tag} range scan across a single shard
curl -s -X POST http://127.0.0.1:8080/api/v1/state/range \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "sec_windows",
    "start_key": "{host-01}:20261114T0000",
    "end_key": "{host-01}:20261114T2359"
  }'

3. Executing Atomic Multi-Key Transactions (TxBatch)

To update multiple namespaces and keys with all-or-nothing ACID atomicity (TX_BEGIN .. StateDelta* .. TX_COMMIT), submit a TxBatch:

BASH
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "tx-order-9001",
    "namespaces": ["wallets", "inventory", "orders"],
    "keys": ["{cust:1001}:usd", "sku:nvme-gen5-4tb", "ord:9001"],
    "deleted": [0, 0, 0],
    "values_json": [
      "{\"owner\":\"Alice Rivera\",\"balance_cents\":84200,\"tier\":\"PRIME\"}",
      "{\"warehouse\":\"us-east-va1\",\"available_qty\":19,\"unit_price_cents\":32900}",
      "{\"order_id\":\"ord:9001\",\"customer\":\"cust:1001\",\"qty\":2,\"total_cents\":65800}"
    ]
  }'

4. Performing Wait-Free Time-Travel Audits (By Offset or HLC Timestamp)

Every mutation response returns committed_offset and committed_ts (nanoseconds). Readers can query historical MVCC epochs without locking or slowing down live writers:

BASH
# Query state exactly as it existed at CommitLog offset 12
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "use_at_offset": true,
    "at_offset": 12
  }'

# Query state as of a specific nanosecond Hybrid Logical Clock timestamp
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "at_timestamp": 1794660496824000000
  }'

5. Invoking Durable Workflows & Resolving External Webhook Awakeables

Durable workflows journal each step in __durable_step so completed side effects are memoized and never re-executed across process restarts or webhook suspensions.

Step 1: Invoke a Workflow That Suspends on an Awakeable Promise

BASH
curl -s -X POST http://127.0.0.1:8080/v1/durable/invoke \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "exec-wire-swift-501",
    "service_name": "StudioApprovalWorkflow",
    "object_key": "wire:swift-501",
    "input_json": "{\"originator\":\"acct:alice\",\"beneficiary\":\"DEUTDEFF\",\"amount_cents\":2500000}"
  }'

The response includes "status": "suspended_awakeable" and "waiting_awakeable": "exec-wire-swift-501:awake:000001".

Step 2: Resolve the Awakeable from an External Webhook or Compliance Service

BASH
curl -s -X POST http://127.0.0.1:8080/v1/durable/awakeable/resolve \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "awakeable_id": "exec-wire-swift-501:awake:000001",
    "callback_token": "studio-cb-token",
    "payload_json": "{\"approved_by\":\"officer-kim\",\"sanctions_check\":\"PASS\"}",
    "resolver": {
      "principal": {
        "id": "usr:compliance-officer-1",
        "roles": ["compliance:approve"]
      },
      "tenant_id": "tenant:global"
    }
  }'

6. Subscribing to Non-Blocking Real-Time CDC Streams (Poll & SSE)

vprevail includes a non-blocking Change-Data-Capture (CDC) event bus with Drop-Oldest + Lag Watermark backpressure protection so slow downstream consumers never stall the write coordinator.

BASH
# 1. Register a filtered CDC subscription (returns subscriber_id)
curl -s -X POST http://127.0.0.1:8080/v1/events/subscribe \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_filter": "orders",
    "key_prefix": "ord:",
    "max_queue": 512
  }'

# 2. Consume events as a text/event-stream SSE batch
curl -s -X POST http://127.0.0.1:8080/v1/events/stream \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{"subscriber_id": 1, "max_events": 64}'

7. Authoring Polyglot Durable Workflows (Python, TypeScript, Go & Rust)

External microservices execute deterministic workflow turns via /v1/durable/polyglot/begin and /v1/durable/polyglot/yield using the official zero-dependency client SDKs bundled in release packages under sdk/.

Python Durable Saga Worker

PYTHON
from vprevail_sdk import VPrevailClient, DurableWorkerContext

client = VPrevailClient(
    "http://127.0.0.1:8080",
    auth_token="vprv-prod-bearer-9f8e7d6c5b4a3210",
)

def wire_settlement_saga(ctx: DurableWorkerContext, req: dict) -> dict:
    # Step 0: Reserve funds (memoized in CommitLog; never re-run on replay)
    hold_id = ctx.run("reserve_funds", lambda: f"hold-{req['tx_id']}")
    ctx.compensate(
        "release_funds",
        lambda: client.put("holds_released", hold_id, {"released": True}),
    )

    # Step 1: Non-blocking durable cooling-off timer (50 ms)
    ctx.sleep("settlement_cooldown", duration_ms=50)

    # Step 2: Suspend worker until compliance officer resolves Awakeable
    decision = ctx.awakeable("compliance_signoff")
    if decision != "APPROVED":
        ctx.fail_terminal(f"Compliance rejected transfer: {decision}")

    # Step 3: Commit final settlement receipt
    return ctx.run("commit_transfer", lambda: {"status": "SETTLED", "hold_id": hold_id})

TypeScript / Node.js Durable Saga Worker

TYPESCRIPT
import { VPrevailClient, DurableWorkerContext } from "@vprevail/sdk";

const client = new VPrevailClient({
  baseUrl: "http://127.0.0.1:8080",
  authToken: "vprv-prod-bearer-9f8e7d6c5b4a3210",
});

export async function runOrderFulfillmentSaga(orderId: string) {
  return await client.runPolyglotWorkflow(
    {
      executionId: `exec-${orderId}`,
      serviceName: "OrderSagaService",
      objectKey: orderId,
      input: { orderId, amountCents: 65800 },
    },
    async (ctx: DurableWorkerContext, input: { orderId: string; amountCents: number }) => {
      const reservationId = await ctx.run("reserve_stock", async () => `resv-${input.orderId}`);
      ctx.compensate("release_stock", async () => {
        await client.put("inventory_releases", reservationId, { released: true });
      });

      await ctx.sleep("fraud_window", 25);
      const verdict = await ctx.awakeable<string>("fraud_webhook");
      if (verdict !== "PASS") {
        await ctx.failTerminal("Fraud engine declined order");
      }
      return { status: "FULFILLED", reservationId };
    }
  );
}

Go Durable Saga Worker

GO
package main

import (
	"time"
	"github.com/vprevail/vprevail-go"
)

func RunGoPaymentSaga(client *vprevail.HttpClient, req *vprevail.PolyglotWorkerRequest) (*vprevail.PolyglotWorkerYield, error) {
	return vprevail.ExecuteTurn(req, func(ctx *vprevail.PolyglotContext) (any, error) {
		var holdID string
		if err := ctx.Run("reserve_funds", func() (any, error) {
			return "hold-tx-9001", nil
		}, &holdID); err != nil {
			return nil, err
		}

		ctx.Compensate(func() error {
			_, err := client.Put("holds_released", holdID, map[string]bool{"released": true})
			return err
		})

		if err := ctx.Sleep("settlement_cooldown", 50*time.Millisecond); err != nil {
			return nil, err
		}

		var decision string
		if err := ctx.Awakeable("compliance_signoff", "cb-token-1", "compliance:approve", &decision); err != nil {
			return nil, err
		}
		if decision != "APPROVED" {
			return nil, vprevail.NewTerminalError("compliance rejected wire: " + decision)
		}

		return map[string]string{"status": "SETTLED", "hold_id": holdID}, nil
	})
}

Rust Durable Saga Worker

RUST
use vprevail::{HttpClient, PolyglotContext, VPrevailError};

pub fn run_rust_payment_saga(
    client: &HttpClient,
    ctx: &mut PolyglotContext,
) -> Result<String, VPrevailError> {
    let hold_id = ctx.run("reserve_funds", || Ok("\"hold-tx-9001\"".to_string()))?;

    let release_hold_id = hold_id.clone();
    let host = client.host_port.clone();
    let token = client.auth_token.clone();
    ctx.compensate(move || {
        let comp_cli = HttpClient::new(&host, &token);
        let _ = comp_cli.put_state("holds_released", &release_hold_id, "{\"released\":true}");
    });

    ctx.sleep("settlement_cooldown", 50_000_000)?;

    let decision = ctx.awakeable("compliance_signoff", "cb-token-1", "compliance:approve")?;
    if decision != "\"APPROVED\"" {
        return Err(VPrevailError::Terminal(format!(
            "compliance rejected transfer: {}",
            decision
        )));
    }

    Ok(format!("{{\"status\":\"SETTLED\",\"hold_id\":{}}}", hold_id))
}

vprevail — End-User Workspace Guide

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This End-User Guide walks self-service developers, quant analysts, and domain users through authenticating at /ui/auth and operating the Self-Service Portal (/ui/portal).


1. Signing In, Requesting Onboarding & Pairing via QR (/ui/auth)

Navigate to http://<host>:<port>/ui/auth to access the Authentication & Onboarding Gate.

Authentication and Onboarding Gate

Tab 1: Sign In

  1. Enter your Principal Identifier (for example usr:alice or admin:root) and Display Name.
  2. Choose your Target Workspace Role:
    • portal — Routes to /ui/portal (isolated personal MVCC state, workflow studio, CDC streams, and Reference App Studios).
    • delegated — Routes to /ui/delegated (scoped namespace exploration, streaming sketches, sandbox replay, and Awakeable approvals).
    • admin — Routes to /ui/admin (global engine telemetry, WAL snapshots, cluster replication, and benchmarks).
  3. Enter your Tenant Namespace (for example tenant:quant) and, when the gateway is started with --auth-token, provide the Cluster Bearer Token.
  4. Select desired Session Scopes (state:read, state:write, durable:invoke, events:subscribe, compliance:approve) using the multi-select chip selector and click Authenticate Session.

Tab 2: Request Scoped Access (Onboarding Queue)

If your principal has not yet been provisioned by a tenant operator, switch to Onboarding Request, specify your justification and required scopes, and click Submit Onboarding Request. Your request is written durably to __ui_onboarding for review in /ui/delegated.

Tab 3: ISO/IEC 18004 QR Session Pairing

Switch to QR Session Pairing (or inspect My Profile & Credentials after signing in) to scan a pure-vector 25x25 ISO/IEC 18004 QR code containing an explicit white quiet zone (#ffffff) for reliable camera scanning in both Daylight and Dark themes.


2. Managing Personal MVCC State & Time-Travel (/ui/portal -> My State & Time-Travel)

Every authenticated portal user receives a dedicated, tenant-isolated MVCC namespace (self:<principal_id>) where reads and writes cannot collide with other principals.

Portal MVCC Key-Value and Time-Travel Studio

Writing Permanent & Ephemeral Records

  1. Enter a Key in Key (supports {tag} partition prefix) — for example {treasury}:usd_operating_pool or {acct}:prefs. Using a {tag} prefix co-locates all related keys inside the same MVCC shard.
  2. Set TTL Nanoseconds (0 for permanent persistence, or a positive nanosecond duration such as 3600000000000 for 1 hour).
  3. Enter valid JSON in JSON Value Payload and click Put Record.
  4. Click Inspect JSON on any row in the table to open the formatted keyboard-accessible JSON Lightbox Inspector (Esc to close).

Time-Travel Point-in-Time Inspection

  1. Note the Updated Offset column on earlier versions of your keys.
  2. Enter any historical CommitLog offset into Time-Travel Offset (0 = latest) (for example 8) and click Query / Time-Travel Scan.
  3. The portal checks out an immutable historical StateView from the MVCC ring buffer in O(1) without locking or affecting concurrent writes. Reset Time-Travel Offset to 0 to return to the live head epoch.

3. Invoking Durable Workflows & Inspecting Step Journals (/ui/portal -> My Workflows & Awakeables)

Switch to My Workflows & Awakeables to launch stateful Virtual Objects and Restate-style durable workflows:

  1. Set a unique Execution ID (for example exec-portal-101), Service Name (StudioEchoWorkflow for immediate completion, or StudioApprovalWorkflow to test external webhook suspension), and Virtual Object Key (obj:user-1).
  2. Provide Input JSON and click Invoke Durable Workflow.
  3. Click Inspect Steps on any execution row to view the persisted __durable_step memoization journal, retry attempt count, registered Saga compensations, and waiting Awakeable ID.

4. Streaming Real-Time CDC Events (/ui/portal -> My Event Subscriptions)

Switch to My Event Subscriptions to observe live mutations across namespaces:

  1. Optionally enter a Namespace Filter (such as studio_bank_ledger or leave empty for all namespaces) and a Key Prefix Filter (such as wire-).
  2. Click Create Subscription to allocate a bounded non-blocking subscriber ring (max_queue = 256).
  3. Trigger writes in another tab (or in Reference App Studios), then click Poll Events (/v1/events/poll) to populate the table or Fetch SSE Stream (/api/v1/events/stream) to inspect the raw text/event-stream wire batch.
  4. Click Unsubscribe when finished to release the subscriber slot cleanly.

5. Exploring Interactive Reference Application Studios (/ui/portal -> Reference App Studios)

The Reference App Studios sub-tab lets you interactively drive four domain reference architectures directly against the live PrevalentEngine:

Reference Application Studios and Double-Entry Ledger

Studio Selection Primary / Counterparty Parameters Interactive Actions
PrevailBank — Double-Entry Core Banking & Wire Ledger Originator (acct:alice), Beneficiary (acct:bob), Amount in cents (25000) 1. Seed Baseline State initializes asset/liability accounts; 2. Execute App Scenario posts balanced DEBIT + CREDIT legs summing strictly to zero.
PrevailAgent — AI Agent Sandbox & O(1) Time-Travel Undo Patch target (file:firewall.conf), Candidate content, Revision 2. Execute App Scenario applies an autonomous sandbox mutation; 3. Time-Travel Undo restores exact pre-mutation state from historical MVCC offset.
PrevailExchange — Price-Time Priority CLOB & Prediction Market Order side (BID or ASK), Symbol, Limit price in cents (55) 1. Seed Baseline State posts resting maker liquidity; 2. Execute App Scenario crosses or rests limit orders with integer collateral conservation.
PrevailTwin — Live-to-Sim Quant Digital Twin & Circuit Breaker Branch profile, Counterparty, Volatility shock in bps (380) 2. Execute App Scenario forks two parallel simulation branches (Twin-A conservative vs. Twin-B aggressive) and evaluates drawdown circuit breakers.

6. Theme Switching & Keyboard Accessibility

  • Daylight / Dark Theme Toggle: Click the Light / Dark toggle button in the top navigation bar to switch between Daylight Paper & Slate (data-theme="light", default) and Dark Mode (data-theme="dark"). Your preference persists in localStorage.
  • Keyboard Shortcuts: All sub-tabs, multi-select chips, and Inspect JSON modals are keyboard-navigable (Tab, Enter, and Escape to dismiss any open Lightbox modal).

vprevail — Administrator & Security Operator Guide

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This Administrator Guide covers day-to-day governance of vprevail clusters using the Delegated Operations Workspace (/ui/delegated), the Global Administrator Console (/ui/admin), and Zero-Trust production deployment topologies.


1. Delegated Operations Workspace (/ui/delegated)

Operators with the delegated or admin role use /ui/delegated to manage tenant namespaces, run online anomaly sketches, replay WAL windows in an isolated sandbox, and approve suspended workflows.

1.1 Tenant Namespaces, {tag} Range Scans & Dynamic Tuples

  • Prefix & Range Explorer: Query any namespace at the latest head (At Offset = 0) or any retained historical offset. Supplying a {tag} prefix (such as {deskA}:) restricts sorted range scans to a single FNV-1a shard.
  • Atomic Multi-Key TxBatch & Tuples: Commit multi-record TX_BEGIN .. TX_COMMIT batches or schema-less dynamic Tuples directly from the operator console, and run targeted Reap Expired TTLs sweeps per namespace.

1.2 Streaming Sketches & Online Anomaly Detection

The Streaming Sketches & Telemetry sub-tab exposes four deterministic constant-memory primitives designed for high-velocity SIEM and financial telemetry:

  1. RunningStats (Welford Variance & EWMA Z-Score): Computes streaming count, mean, sample standard deviation, exponentially weighted moving average (EWMA), and instant anomaly Z-scores in O(1) RAM (40 bytes per metric).
  2. 64-Register HyperLogLog: Estimates distinct cardinality (such as unique source IPs or trading accounts) in 64 bytes of state.
  3. BoundedRing Circular Buffers: Retains the most recent N observations per entity with deterministic oldest-item eviction.
  4. Shannon Entropy Analyzer: Computes payload entropy in bits/byte (0.0 .. 8.0) to flag obfuscated scripts, base64-encoded exfiltration, or high-entropy anomalies.

1.3 Ephemeral Sandbox WAL Replay & Backtesting

Ephemeral Sandbox Replay and Time-Travel Version Inspector

In Sandbox Replay & Backtesting, enter a [From Offset .. To Offset] window and click Run Ephemeral Sandbox Replay. vprevail forks a zero-copy Copy-on-Write StateSpace without acquiring writer locks on production traffic, replays the historical CommitLog window, reports replay latency in microseconds, and lists every key diff (added, modified, deleted).

1.4 Awakeable Webhook Approvals & Onboarding Review

Delegated Durable Workflows and Awakeable Resolution

  • Durable Approvals & Timers: Click Select on any waiting Awakeable promise to populate its ID, verify the callback token and JSON approval payload, and click Resolve Awakeable (or Advance Durable Timers to trigger due sleep steps).
  • Onboarding Requests: Switch to Onboarding Requests to approve or reject pending access requests submitted via /ui/auth. Approving a request automatically provisions the principal policy in __ui_principals.

2. Global Administrator Console (/ui/admin)

Admin Cluster, MVCC Shards, and WAL Telemetry

2.1 Engine & 16-Shard MVCC Governance

Monitor the five core prevalence indicators in real time:

  • Node / Gateway ID: Active logical node and HTTP gateway identifiers.
  • MVCC Epoch: Monotonically increasing published StateSpace generation counter.
  • Committed / Next Offset: Highest durable CommitLog record offset vs. next allocatable sequence number.
  • PrevalentClock (ns): Current monotonic Hybrid Logical Clock watermark.
  • Retained History: Active historical StateView count vs. configured ring capacity (max_version_history).

The MVCC Namespace & 16-Shard Partition Inventory table displays entry counts, active shards (k / 16), and current __system_fencing terms for every user and internal namespace (__durable_exec, __durable_step, __durable_awake, __system_fencing).

2.2 CommitLog, Non-Blocking .snap Checkpoints & Segment Compaction

Switch to CommitLog, Snapshots & Inspector to manage disk lifecycle safely:

  1. Create .snap Checkpoint: Serializes the current immutable StateView to an atomic CRC32-verified snapshot file without pausing live writes, pruning older snapshots beyond keep_latest.
  2. Run CRC32 WAL Inspector: Scans every .snap and .log segment on disk, verifying all 32-byte VPRV headers, IEEE CRC32 checksums, and TX_BEGIN / TX_COMMIT / TX_ABORT counts.
  3. Truncate Old Rolled Segments: Deletes rolled .log and .idx segments whose maximum offset is strictly less than a verified .snap checkpoint offset. The active head segment is never deleted.

2.3 Cluster Replication & Split-Brain Shard Fencing

Switch to Cluster Replication & Shard Mobility to execute:

  • Ping Peer: Verify authenticated TCP reachability and constant-time cluster_secret match against a remote peer.
  • Pull Log From Peer: Pull and deterministically replay committed WAL frames from a primary node.
  • Push Namespace To Peer: Transfer an entire namespace (wrapped in TX_BEGIN .. TX_COMMIT) to a target node.
  • Advance Local Shard Fencing Term: Increment the WAL-persisted __system_fencing epoch for a namespace or specific shard (0..15) before migrating ownership so stale writers are deterministically rejected.

2.4 Durable Journal Compaction & Zero-Trust Policy Provisioning

  • Compact Completed Journals (admin-durable): Prunes historical __durable_exec, __durable_step, __durable_timer, and __durable_awake keys for terminal executions (completed, failed_terminal, cancelled) older than a cutoff timestamp to keep active RAM lean.
  • Principal Policy Provisioning (admin-security): Provision multi-role principals (admin, delegated, portal, compliance:approve, risk:evaluate) and audit active defense-in-depth enforcement across all subsystems.

3. Production Zero-Trust Network & Systemd Deployment

vprevail intentionally keeps TLS/mTLS termination and kernel tunnel encryption outside its pure-V memory space to eliminate OpenSSL CVE surface area. In production:

  1. Bind Listeners to Loopback or Encrypted Mesh Interfaces: Bind --addr 127.0.0.1:8080 behind an mTLS reverse proxy (Caddy, Envoy, or NGINX) or bind to a private WireGuard interface (10.200.0.1:8080).
  2. Always Configure Non-Empty Secrets: Pass a high-entropy 32+ byte --auth-token (256 bits of CSPRNG entropy) in production.
  3. Dedicated NVMe Volume: Mount --data-dir ./data on local NVMe storage (ext4 or xfs with noatime) and reserve 30% free disk headroom for segment rolling and .snap atomic renames.

Reference Linux systemd Unit (deploy/vprevail.service)

INI
[Unit]
Description=vprevail Distributed System Prevalence & Durable Execution Engine
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vprevail
Group=vprevail
WorkingDirectory=./data
EnvironmentFile=/etc/vprevail/vprevail.env
ExecStart=./vprevail serve --config /etc/vprevail/vprevail.json
Restart=on-failure
RestartSec=3s
TimeoutStopSec=15s
KillSignal=SIGTERM
LimitNOFILE=65536
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=./data

[Install]
WantedBy=multi-user.target

vprevail — Operations Runbooks & Reference Application Use Cases

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This guide combines Day-2 Operational & Incident Response Runbooks with complete architectural walkthroughs and external execution examples for vprevail's five domain applications (PrevailBank, PrevailAgent, PrevailExchange, PrevailTwin, and PulseLedger) plus distributed cluster topologies (PrevailFlow, PrevailKV, and PrevailMetrics).


1. Day-2 Operational Runbooks & Self-Healing IR Playbooks

1.1 Automated Self-Healing Matrix

Fault / Anomaly Built-In Self-Healing Mechanism Operator Verification
Power-Loss Torn Tail Frame Cold startup scans the active .log segment, detects partial trailing header/body bytes, truncates cleanly to the last verified IEEE CRC32 frame boundary, and discards uncommitted TX_BEGIN batches. Run ./vprevail inspect <data_dir> and confirm Total WAL Frames equals Committed plus balanced transaction markers.
Missing or Truncated .idx File Startup automatically reconstructs the 24-byte sparse offset/timestamp index by scanning verified frames in the corresponding .log segment. Zero downtime; verify segment count via /api/v1/wal/inspect.
NTP Backward Wall-Clock Jump PrevalentClock CAS loop refuses to move backward, incrementing the logical nanosecond counter monotonically until wall time catches up. Check PrevalentClock (ns) in /ui/admin (admin-engine).
Slow or Disconnected CDC Consumer Bounded subscriber ring evicts oldest unread notifications (Drop-Oldest) and increments dropped_count + min_retained_offset watermark without stalling commits. Poll /v1/events/poll and trigger incremental scan catch-up if dropped_count > 0.
Transient Downstream API Timeout Durable run_with_retry applies bounded exponential backoff while preserving memoized prior steps. Inspect attempt counts in /ui/admin (admin-durable).

1.2 Incident Response Playbooks (IR-01 through IR-05)

IR-01: Mid-Log CRC32 Bit-Rot Alert

  • Symptom: Startup or ./vprevail inspect reports a CRC32 mismatch inside a non-tail frame (caused by faulty NVMe flash or uncorrectable storage bit-rot).
  • Resolution:
  1. Do not overwrite the affected directory; archive it for hardware diagnostics.
  2. Provision a clean --data-dir on healthy NVMe media.
  3. Restore the latest verified .snap checkpoint from backup or pull committed history from an online replica via /api/v1/cluster/op (pull_log).

IR-02: Split-Brain / Stale Primary After Network Partition

  • Symptom: A partitioned primary node comes back online after Virtual Object or shard ownership was migrated to a standby peer.
  • Resolution:
  1. On the authoritative target node, verify that __system_fencing holds the higher monotonic fencing term via /ui/admin (admin-cluster -> Check Fencing Term).
  2. Advance the fencing term on the decommissioned primary before reconnecting it as a read-only consumer replica. Any stale local write or timer resumption on the old primary is deterministically rejected.

IR-03: Unbounded Disk Growth on High-Write Node

  • Symptom: Rolled .log segments accumulate on ./data.
  • Resolution:
  1. Confirm all async replicas have pulled past the target offset.
  2. Trigger a non-blocking .snap checkpoint:
BASH
     curl -s -X POST http://127.0.0.1:8080/api/v1/wal/snapshot \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
       -d '{"keep_latest": 3}'
  1. Truncate rolled segments strictly older than the returned snapshot offset:
BASH
     curl -s -X POST http://127.0.0.1:8080/api/v1/wal/compact \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
       -d '{"min_offset": 50000}'

IR-04: Suspended Durable Workflows Awaiting Compliance Sign-Off

  • Symptom: High count of suspended_awakeable executions in /ui/delegated.
  • Resolution: Review pending Awakeables in /ui/delegated (delegated-durable) and either resolve with an authorized compliance:approve principal or cancel terminal stale executions via /api/v1/durable/manage ({"action":"cancel","execution_id":"..."}), which automatically runs registered LIFO Saga compensations.

IR-05: High RAM Utilization from Completed Workflow Journals or Expired Keys

  • Resolution: Trigger global TTL reaping (/api/v1/state/reap) and prune completed durable step journals (/api/v1/durable/manage with {"action":"compact_before"}).

2. Reference Application #1: PrevailBank (Core Banking & Double-Entry General Ledger)

PrevailBank models an institutional core banking ledger and cross-border SWIFT wire settlement pipeline where every financial mutation posts balanced Debit (-cents) and Credit (+cents) legs summing strictly to zero across every MVCC epoch.

Key Architectural Mechanics

  • Two-Phase Funds Reservation: Initiating an international wire places funds into held_cents (available_cents = balance_cents - held_cents) and registers a LIFO Saga compensation (release_wire_hold) before invoking external sanctions screening.
  • Unified Ledger + Workflow WAL: Sanctions retries, cooling-off timers, compliance officer Awakeables, and general-ledger postings commit to the exact same CommitLog, eliminating dual-write drift.
  • Encrypted Principal Context: Customer and compliance identities are sealed at rest using NIST SP 800-38D AES-256-GCM with execution_id AAD binding, while ephemeral bearer tokens are stripped prior to disk persistence.

Running & Querying PrevailBank

BASH
# Run the standalone compiled PrevailBank reference binary (6-stage end-to-end banking simulation)
./dist/bin/windows/banking_ledger.exe   # Windows
./dist/bin/linux/banking_ledger         # Linux

# Or drive PrevailBank live over REST via the Gateway Studio endpoint:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "bank",
    "action": "execute",
    "param_a": "acct:alice",
    "param_b": "acct:bob",
    "amount": 42500,
    "target_offset": 1
  }'

3. Reference Application #2: PrevailAgent (Autonomous AI Agent Sandbox & O(1) Undo)

PrevailAgent provides a deterministic guardrail runtime for autonomous coding, infrastructure, and security response agents.

Key Architectural Mechanics

  • Zero-Rebilling LLM Step Memoization: Expensive LLM tool-planning turns execute inside memoized durable steps. If an agent pauses for human approval or restarts after a crash, prior token-billed LLM responses are replayed instantly from the WAL at zero API cost.
  • Human-in-the-Loop Awakeable Gate: High-impact mutations (such as firewall policy edits or production deployments) suspend automatically on an Awakeable until an operator with the required RBAC role approves or rejects the diff.
  • O(1) Time-Travel Workspace Undo: Every agent tool patch records its pre-patch CommitLog offset, enabling instant point-in-time state restoration or LIFO Saga rollback if post-patch validation fails.

Running & Querying PrevailAgent

BASH
# Run the standalone compiled PrevailAgent reference binary
./dist/bin/windows/agent_sandbox.exe    # Windows
./dist/bin/linux/agent_sandbox          # Linux

# Execute a sandboxed agent patch and trigger O(1) Time-Travel Undo via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "agent",
    "action": "undo",
    "param_a": "policy:prod_egress",
    "param_b": "v1_baseline",
    "amount": 1,
    "target_offset": 1
  }'

4. Reference Application #3: PrevailExchange (Sub-Microsecond CLOB & Prediction Market)

PrevailExchange implements a deterministic Central Limit Order Book (CLOB) and binary prediction market matching engine inspired by LMAX Disruptor and Polymarket/Kalshi settlement pipelines.

Key Architectural Mechanics

  • Single-Writer Price-Time Priority (FIFO): Serializing order matching on the single-writer PrevalentEngine eliminates lock contention on hot price levels while delivering sub-microsecond matching determinism.
  • Strict Integer Collateral Conservation: Escrowed trader collateral plus settled payouts is conserved to the exact integer cent across partial fills, maker price-improvement refunds, cancellations, and oracle market resolution.
  • Wait-Free Level-2 Market Data: Market-data feeds read immutable StateView order-book snapshots concurrently without delaying order matching by a single nanosecond.

Running & Querying PrevailExchange

BASH
# Run the standalone compiled PrevailExchange reference binary
./dist/bin/windows/exchange_matching.exe  # Windows
./dist/bin/linux/exchange_matching        # Linux

# Submit an immediate-crossing BID limit order at 55 cents via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "exchange",
    "action": "execute",
    "param_a": "BID",
    "param_b": "MKT-FED-RATE",
    "amount": 55,
    "target_offset": 1
  }'

5. Reference Application #4: PrevailTwin (Live-to-Sim Quant Digital Twin)

PrevailTwin eliminates "Live-to-Sim" code skew in algorithmic trading and risk engineering by running the exact same deterministic command handlers across live market ingestion and forked counterfactual simulations.

Key Architectural Mechanics

  • Zero-Copy Counterfactual Forking: Forks Twin-A (conservative risk-off flatten) and Twin-B (aggressive momentum) directly from a live production MVCC epoch at near-zero memory cost.
  • Volatility Circuit-Breaker Sagas & TWAP Fast-Forwarding: Evaluates online EWMA volatility shocks (bps), trips circuit-breaker Sagas automatically when drawdown thresholds are breached, and fast-forwards multi-slice TWAP execution timers deterministically in replay time.

Running & Querying PrevailTwin

BASH
# Run the standalone compiled PrevailTwin reference binary
./dist/bin/windows/trading_twin.exe     # Windows
./dist/bin/linux/trading_twin           # Linux

# Fork a 420 bps volatility shock counterfactual simulation via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "twin",
    "action": "execute",
    "param_a": "desk:stat-arb",
    "param_b": "shock-420bps",
    "amount": 420,
    "target_offset": 1
  }'

6. Reference Application #5: PulseLedger (Flash-Sale E-Commerce & Fulfillment)

PulseLedger demonstrates hybrid multi-model storage during high-concurrency retail flash sales by combining three storage representations inside a single atomic transaction:

  1. wallets Namespace (Integer Values): Customer spending balances in minor currency units (cents).
  2. inventory Namespace (Dynamic Tuples): Compact positional tuples [product_title, warehouse_zone, available_qty, unit_price_cents].
  3. orders Namespace (Structured Receipts): Numbered order tickets stamped with deterministic PrevalentClock timestamps and CommitLog offsets, paired with a role-gated (orders:ship) durable carrier-label fulfillment workflow and async replica catch-up.
BASH
# Execute an atomic flash-sale checkout across wallets, inventory, and orders via REST:
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "pulse-flash-ord-9001",
    "namespaces": ["wallets", "inventory", "orders"],
    "keys": ["cust:alice", "sku:nvme-2tb", "ord:9001"],
    "deleted": [0, 0, 0],
    "values_json": [
      "{\"balance_cents\":20000}",
      "[\"Gen4 NVMe 2TB SSD\",\"us-east-rack-4\",8,15000]",
      "{\"order_id\":\"ord:9001\",\"customer_id\":\"cust:alice\",\"sku\":\"sku:nvme-2tb\",\"qty\":2,\"total_cents\":30000}"
    ]
  }'

7. Distributed Cluster Blueprints (PrevailFlow, PrevailKV, PrevailMetrics)

Blueprint Primary Workload Recommended vprevail Configuration
PrevailFlow Geo-distributed durable workflow & Virtual Object actor mesh Enable AES-256-GCM SubjectContext sealing, configure two-tier remote durable tokens, and advance __system_fencing epochs prior to live Virtual Object migration across regions.
PrevailKV Multi-region low-latency configuration, session & feature-flag store Partition tenant keys with {tenant_id}: affinity tags across 32 or 64 shards, run continuous PullReplicator read replicas per availability zone, and snapshot hourly.
PrevailMetrics / PrevailSec High-velocity SIEM correlation, IoT telemetry & anomaly detection Use {host_id}: co-located time windows with deterministic ttl_ns watermarks, maintain RunningStats + HyperLogLog sketches in RAM, and backtest detection rules via /api/v1/sandbox/replay.

vprevail — Configuration, CLI & REST API Reference

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This reference documents all standalone vprevail CLI commands and flags, reference binary executables, engine/cluster/durable/gateway configuration parameters, and HTTP/1.1 JSON & SSE endpoints.


1. Standalone vprevail CLI Reference

TEXT
vprevail 1.0.0 — Pure-V Distributed System Prevalence, MVCC & Durable Execution Engine

Usage:
  vprevail <command> [options]

Commands:
  serve, ui                    Start the HTTP/1.1 Gateway, optional Cluster TCP node & Web Control Plane
  bench                        Execute the 35-workload subsystem & reference app benchmark suite
  inspect <dir>                Verify IEEE CRC32 WAL segments (.log), sparse indexes (.idx), & snapshots (.snap)
  snapshot <dir>               Recover state in <dir> and write a verified atomic .snap checkpoint
  compact <dir> <min_offset>   Truncate rolled WAL segments strictly older than <min_offset>
  version                      Print the vprevail engine version
  help                         Display this CLI reference

vprevail serve / vprevail ui Flags & Environment Variables

Flag Environment Variable Default Description
--config <path> VPREVAIL_CONFIG "" Load JSON configuration manifest (e.g., config/vprevail.example.json).
--addr <host:port>, -a VPREVAIL_ADDR 127.0.0.1:8080 TCP bind address and port for the HTTP/1.1 Gateway & Web Control Plane (16 KiB header cap, 4 MiB body cap).
--data-dir <path>, -d VPREVAIL_DATA_DIR data/ui_studio Directory storing .log segments, .idx sparse indexes, and .snap checkpoints.
--auth-token <secret> VPREVAIL_AUTH_TOKEN "" (fail-closed) Static Zero-Trust Bearer token verified via 256-byte padded constant-time comparison (prefer env var over CLI arg).
--node-id <id> VPREVAIL_NODE_ID studio-node-1 Logical node identifier stamped onto health, overview, and mutation responses.
--cluster-addr <host:port> VPREVAIL_CLUSTER_ADDR "" Enables the ClusterNode binary TCP replication listener on <host:port>.
--cluster-secret <secret> VPREVAIL_CLUSTER_SECRET "" Shared inter-node authentication secret (prefer env var over CLI arg).
--read-only-follower VPREVAIL_READ_ONLY_FOLLOWER false Rejects direct client write RPCs on ClusterNode to prevent split-brain writes.
--sync VPREVAIL_SYNC false Forces an OS fsync / _commit barrier on every CommitLog frame/batch write (RPO = 0 durability).
--structured-logs VPREVAIL_STRUCTURED_LOGS false Emits JSON access and security audit logs to stderr.
--cookie-secure VPREVAIL_COOKIE_SECURE false Adds the Secure attribute to HttpOnly; SameSite=Strict session cookies (enable behind TLS).
--studio-demo VPREVAIL_STUDIO_DEMO false Registers built-in Studio demo workflows (StudioEchoWorkflow, StudioApprovalWorkflow).
--allow-insecure-dev VPREVAIL_ALLOW_INSECURE_DEV false Permits unauthenticated Studio login when auth_token is empty (local development only).
(env/config only) VPREVAIL_ENCRYPTION_KEY_HEX "" Optional 64-hex-char (32-byte) AES-256-GCM key sealing SubjectContext records at rest.

vprevail bench & vprevail inspect Flags

Command & Flag Description
vprevail bench Runs all 35 empirical subsystem, codec, MVCC, cluster, durable, polyglot, and SIEM benchmarks at full production iteration counts and prints the cloud sizing table.
vprevail bench --quick (-q) Runs fast verification iteration counts across all 35 workloads (~1–2 seconds).
vprevail inspect <data_dir> Scans all .snap checkpoints and .log segments in <data_dir>, verifying every 32-byte VPRV header and IEEE CRC32 checksum without mutating state.

Bundled Reference Application Executables (dist/bin/<platform>/)

Executable Domain Description
vprevail / vprevail.exe Core Server & CLI Standalone HTTP/1.1 Gateway, 4-workspace Web UI Control Plane, WAL inspector, and benchmark runner.
banking_ledger / .exe Core Banking Runs the 6-stage PrevailBank double-entry ledger, SWIFT wire hold, Awakeable approval, snapshot, and fenced migration suite.
agent_sandbox / .exe AI Agent Guardrails Runs the 6-stage PrevailAgent memoized LLM tool-use, human-in-the-loop gate, O(1) time-travel undo, and migration suite.
exchange_matching / .exe Financial Exchange Runs the 6-stage PrevailExchange price-time FIFO limit order book, collateral conservation, and oracle settlement suite.
trading_twin / .exe Quant Digital Twin Runs the 6-stage PrevailTwin Live-to-Sim counterfactual fork, volatility circuit-breaker Saga, and TWAP fast-forward suite.

2. Runtime Configuration Reference (JSON / TOML Parameters)

When embedding or configuring vprevail services via structured deployment manifests, the four subsystem configuration blocks expose the following parameters:

2.1 Engine & MVCC Configuration (engine)

Parameter Type Default Description
node_id string "node-1" Unique logical identifier for this PrevalentEngine instance.
data_dir string "./data" Filesystem path for .log, .idx, and .snap persistence.
default_codec string "msgpack_map" Default serialization format: "msgpack_tuple", "msgpack_map", "json", or "raw_bytes".
sync_on_write bool false When true, flushes OS buffers to non-volatile storage on every WAL append/commit.
max_segment_bytes i64 67108864 (64 MiB) Maximum active .log segment size before rolling to a new zero-padded segment file.
index_interval_bytes i64 4096 (4 KiB) Byte stride between 24-byte sparse .idx entries (offset, file_pos, timestamp).
shard_count int 16 Number of FNV-1a Copy-on-Write shards per namespace (16, 32, 64, or 128).
max_version_history int 64 (128 in UI) Number of historical MVCC StateView epochs retained in the in-memory time-travel ring.

2.2 Cluster Transport Configuration (cluster)

Parameter Type Default Description
listen_addr string "127.0.0.1:9100" TCP bind address for inter-node WAL replication and subgraph transfers.
cluster_secret string (required) Shared peer authentication secret compared in constant time (padded to 256 bytes).
io_timeout_ms int 5000 Read/write TCP socket deadline per RPC frame (4 MiB max RPC payload cap).

2.3 Durable Execution Configuration (durable)

Parameter Type Default Description
default_codec string "msgpack_tuple" Default journal codec for step outputs and Virtual Object state.
encryption_key_hex string "" Optional 64-hex-char (32-byte) AES-256-GCM master key sealing SubjectContext records at rest.
max_retry_attempts int 3 Default retry ceiling for transient step failures in run_with_retry.

2.4 HTTP/1.1 Gateway Configuration (gateway)

Parameter Type Default Description
gateway_id string "gateway-1" Identifier included in /v1/health and QR pairing URIs.
listen_addr string "127.0.0.1:8080" HTTP/1.1 TCP bind address (16 KiB header cap, 4 MiB body cap). Unauthenticated probes exposed at /healthz, /readyz, and /metrics.
auth_token string "" Optional static Bearer token required alongside or in place of UI session tokens.

Example Deployment Configuration (vprevail.toml)

TOML
[engine]
node_id = "prod-eu-central-1"
data_dir = "./data"
default_codec = "msgpack_map"
sync_on_write = true
max_segment_bytes = 67108864
index_interval_bytes = 4096
shard_count = 32
max_version_history = 128

[cluster]
listen_addr = "10.200.0.11:9100"
cluster_secret = "replace-with-32-byte-csprng-cluster-secret"
io_timeout_ms = 5000

[durable]
default_codec = "msgpack_tuple"
max_retry_attempts = 5

[gateway]
gateway_id = "prod-eu-central-1-gw"
listen_addr = "127.0.0.1:8080"
auth_token = "replace-with-32-byte-csprng-gateway-token"

3. Complete HTTP/1.1 REST & Control-Plane API Reference

3.1 Public Browser & Authentication Endpoints

Method Path Description
GET /, /ui, /ui/auth Renders the Authentication, Scope Onboarding & ISO 18004 QR Pairing Gate.
GET /ui/portal Renders the End-User Self-Service Portal workspace.
GET /ui/delegated Renders the Scoped / Delegated Operations workspace.
GET /ui/admin Renders the Global Administrator Console workspace.
GET /ui/docs Serves the rendered End-User HTML Documentation Suite (dist/docs/user/index.html).
GET /logo.svg, /icon.svg Serves pure-vector brand assets with image/svg+xml caching headers.
POST /api/v1/auth/login Authenticates a principal and mints a vprv_sess_* session token + Set-Cookie.
POST /api/v1/auth/register Submits a scoped access request into __ui_onboarding.
POST /api/v1/auth/logout Revokes the active session token from __ui_sessions.

3.2 Core Data-Plane, Durable & CDC Endpoints (Bearer Auth Required)

Method Path Key Request Fields Description
GET /v1/health (none) Returns status, gateway_id, node_id, epoch, last_offset, and next_offset.
POST /v1/state/get namespace, key, at_offset, at_timestamp Wait-free live or historical point lookup.
POST /v1/state/put namespace, key, value_json, ttl_ns Writes a JSON record with optional deterministic nanosecond TTL.
POST /v1/state/delete namespace, key Atomically deletes a key and records a StateDelta tombstone in the WAL.
POST /v1/state/scan namespace, prefix, max_items, at_offset Sorted prefix scan across live or historical MVCC state.
POST /v1/tx/batch tx_id, namespaces, keys, deleted, values_json Commits an atomic multi-namespace TX_BEGIN .. TX_COMMIT batch.
POST /v1/commands/execute cmd_name, payload_json Executes a registered deterministic CommandHandler on the coordinator.
POST /v1/durable/invoke execution_id, service_name, object_key, input_json Invokes or resumes a durable workflow / Virtual Object.
POST /v1/durable/awakeable/resolve awakeable_id, callback_token, payload_json, resolver Resolves a suspended Awakeable promise under RBAC verification.
POST /v1/durable/polyglot/begin execution_id, service_name, object_key, input_json Starts or replays a polyglot SDK workflow turn, returning memoized step history.
POST /v1/durable/polyglot/yield execution_id, yield_kind, steps, output_json Commits new steps, timers, Awakeables, or terminal output from an external SDK worker.
POST /v1/events/subscribe namespace_filter, key_prefix, max_queue Registers a non-blocking CDC event stream subscriber.
POST /v1/events/poll subscriber_id, max_events Polls queued CDC mutation events in JSON format.
POST /v1/events/stream subscriber_id, max_events Streams queued CDC events in text/event-stream (SSE) format.
POST /v1/events/unsubscribe subscriber_id Releases an active CDC subscriber ring buffer.

3.3 Operator & Control-Plane Telemetry Endpoints (Bearer Auth Required)

Method Path Description
GET /api/v1/self/session Returns active principal profile, roles, scopes, latest offset, and session QR SVG.
POST /api/v1/self/state Isolated put / list / delete + time-travel scan inside self:<principal>.
GET /api/v1/engine/overview Returns live MVCC epoch, HLC timestamp, retained versions, and 16-shard namespace table.
GET /api/v1/wal/inspect Runs full IEEE CRC32 diagnostic inspection across .log and .snap files.
POST /api/v1/wal/records Reads decoded WAL frame headers and payload sizes starting from from_offset.
POST /api/v1/wal/snapshot Creates a non-blocking .snap checkpoint and prunes older snapshots (keep_latest).
POST /api/v1/wal/compact Truncates rolled .log/.idx segments strictly older than min_offset.
POST /api/v1/cluster/op Runs ping, pull_log, push_namespace, fencing_advance, or fencing_get.
POST /api/v1/sandbox/replay Forks an ephemeral zero-copy StateSpace, replays [from_offset..to_offset], and returns key diffs.
POST /api/v1/sketches/stats Updates Welford RunningStats + EWMA and evaluates online anomaly Z-scores.
POST /api/v1/sketches/hll Updates 64-register HyperLogLog cardinality estimators.
POST /api/v1/sketches/ring Pushes items into a BoundedRing circular telemetry buffer.
POST /api/v1/sketches/entropy Computes Shannon entropy (bits/byte) on candidate command/payload strings.
POST /api/v1/apps/scenario Executes interactive seed, execute, and undo scenarios across the 4 Reference Studios.
POST /api/v1/admin/bench Runs live in-process codec, MVCC checkout, and streaming sketch micro-benchmarks.

vprevail — Performance Benchmarks & Cloud Sizing Guide

vprevail — Distributed In-Memory MVCC & Durable Execution Engine

This guide presents empirical subsystem and workload measurements from vprevail bench (-prod optimized builds), explains durability flush trade-offs, compares vprevail against external storage engines, and provides RAM capacity formulas and cloud instance sizing projections.


1. Executive Throughput & Latency Summary

Measured on an 8-core x86_64 workstation with local Gen4 NVMe storage using ./vprevail bench:

Architectural Stratum Representative Workload Measured Throughput Latency (ns/op or us/op)
1. Wire Framing & Codecs MsgPack Tuple Encode + 32B CRC32 Frame + Decode 1,380,000+ ops/s ~720 ns (148 B wire frame)
1. Wire Framing & Codecs MsgPack Map Encode + 32B CRC32 Frame + Decode 980,000+ ops/s ~1.02 us (214 B wire frame)
1. Wire Framing & Codecs JSON RFC 8259 Encode + 32B CRC32 Frame + Decode 640,000+ ops/s ~1.56 us (256 B wire frame)
2. 16-Shard CoW MVCC Wait-Free StateView Checkout + Typed Point Lookup 6,800,000+ ops/s ~145 ns (zero reader locks)
2. 16-Shard CoW MVCC Pure In-Memory Dirty-Shard CoW {tag} Mutation 3,850,000+ ops/s ~258 ns (1/16 shard clone)
2. 16-Shard CoW MVCC Historical view_at_offset Time-Travel Lookup 5,200,000+ ops/s ~190 ns (binary search over ring)
3. Engine & CommitLog Buffered Sequential WAL Mutation (sync_on_write: false) 145,000+ tx/s ~6.8 us
3. Engine & CommitLog Atomic 10-Key TxBatch (TX_BEGIN .. TX_COMMIT, buffered) 62,000+ batches/s (620K keys/s) ~16.1 us per batch
3. Engine & CommitLog Hardware-Synced WAL Commit (sync_on_write: true, NVMe) 9,500 – 18,500 tx/s ~54 – 105 us (NVMe fsync bound)
3. Engine & CommitLog Sparse 24B .idx Binary-Search Historical Seek 32,000+ seeks/s ~31.2 us (O(log N))
4. Cluster Replication Authenticated TCP pull_log_from_peer Catch-Up 115,000+ records/s ~8.7 us per replicated record
5. Durable Execution Memoized 3-Step Workflow Replay (Idempotent Hit) 420,000+ turns/s ~2.38 us (zero side-effect re-run)
6. Reference Workloads PrevailExchange Price-Time FIFO Order Match + WAL 118,000+ orders/s ~8.4 us
6. Reference Workloads PrevailBank Balanced 2-Leg Double-Entry Transfer + WAL 94,000+ transfers/s ~10.6 us
8. SIEM & Streaming RunningStats + HyperLogLog + BoundedRing Observe 14,500,000+ ops/s ~68 ns (O(1) fixed memory)
8. SIEM & Streaming Ephemeral Counterfactual sandbox_replay (8-Cmd Window) 24,000+ replays/s ~41.5 us (zero-copy fork + diff)

2. Durability Flush Mode Trade-Off Matrix

Flush Configuration Crash Survival Guarantee Typical Throughput (Local NVMe) Recommended Workload
Buffered OS Page Cache (sync_on_write = false) Survives vprevail process crashes and restarts (O_APPEND to kernel page cache); abrupt kernel panic or power loss may lose the last ~1–5 seconds of buffered frames (RPO > 0). 110K – 240K ops/s Low-latency caches, session stores, SIEM telemetry windows, AI agent sandboxes, and multi-node clusters where peers pull continuously.
Amortized TxBatch + --sync (sync_on_write = true with batched writes) Survives process kill, kernel panic, and sudden host power loss (RPO = 0 for every committed batch). 80K – 350K keys/s (8K – 25K batches/s) Core banking ledgers (PrevailBank), exchange clearing (PrevailExchange), and high-volume event ingestion.
Single-Key Strict --sync (sync_on_write = true per individual put) Strict per-operation power-loss durability (RPO = 0), bounded physically by storage fsync round-trip latency. 2,200 – 32,000 tx/s (storage-dependent) Low-concurrency compliance registries, root fencing transitions, and human-driven approval workflows.

3. Architectural Comparison vs. External Storage Systems

Capability vprevail Redis / Valkey PostgreSQL TigerBeetle Temporal / Restate
Active State Residence 100% In-RAM 16-Shard CoW MVCC In-RAM Single-Version Dict Disk B-Tree + Shared Buffer Pool In-RAM / Direct-I/O LSM External DB / RocksDB
Point-in-Time Time-Travel Built-in O(1) Offset & HLC Views None Requires pg_partman / Temporal Tables Historical Transfer Immutable Log Event History Replay Only
Multi-Key ACID Transactions Deterministic Single-Writer TxBatch & Closures Lua Scripts (no automatic rollback) MVCC + Lock Manager (2PL / SSI) Fixed Domain Account/Transfer Only Virtual Object Per-Key Only
Built-In Durable Workflows Native DurableRuntime + Sagas + Awakeables in same WAL None External Queue / Polling None Native Orchestrator (separate state DB)
Counterfactual Sandbox Fork Zero-Copy sandbox_replay with Key Diffs None Full DB Clone Required None Replay Debugger Only
External C / Runtime Dependencies Zero (single static-style pure-V binary) libc +jemalloc/TLS Heavy multi-process installation Zero (Zig binary, fixed schema) Multi-service cluster + DB

4. RAM Capacity Planning Formula

Because vprevail is a System Prevalence engine, the active keyspace (StateSpace) must fit comfortably within physical RAM without triggering OS swap thrashing.

Use the following sizing formula for capacity planning:

TEXT
Total_RAM_Bytes =
    (Active_Keys * (Avg_Key_Bytes + Avg_Payload_Bytes + 96_Byte_Record_Overhead))
  * (1.0 + Retained_History_Epochs * Avg_Mutated_Shard_Fraction)
  * 1.35_Headroom_Factor

Worked Sizing Example

  • Active Dataset: 10,000,000 structured records averaging 32 B key + 160 B MsgPack Tuple payload + 96 B map/record metadata = 288 B/key -> 2.88 GB base StateSpace.
  • MVCC Time-Travel Ring: max_version_history = 64 epochs where each {tag} batch mutates 1/16 (6.25%) of one namespace (~400 MB historical CoW delta retention).
  • Recommended Instance RAM: (2.88 GB + 0.40 GB) * 1.35 = ~4.5 GB active footprint -> deploy on an 8 GB RAM instance (leaving ~3.5 GB for OS page cache and non-blocking .snap serialization).

5. Cloud & Bare-Metal Sizing Projections

The following reference matrix matches vprevail's built-in capacity model across popular VPS and public cloud instance families:

Provider / Instance Tier CPU & RAM Specification Storage Backend Wait-Free MVCC Reads/s Buffered WAL Writes/s Synced fsync Commits/s Peer Replication/s Recommended Max Active State & Shards
Hetzner CX22 / CPX11 2 vCPU (Shared x86) / 4 GB RAM Ceph Network NVMe 1.4M - 2.2M ops/s 45K - 75K ops/s 800 - 1,800 tx/s 35K - 60K rec/s 1.8 GB (16 shards)
Hetzner CAX11 / CAX21 2–4 vCPU (Ampere ARM64) / 4–8 GB Ceph Network NVMe 1.8M - 2.8M ops/s 55K - 90K ops/s 900 - 2,000 tx/s 45K - 75K rec/s 4.5 GB (32 shards)
DigitalOcean Premium Droplet 2 vCPU (AMD/Intel) / 4 GB RAM Local NVMe SSD 1.6M - 2.5M ops/s 50K - 85K ops/s 2,200 - 4,500 tx/s 40K - 70K rec/s 2.0 GB (16 shards)
Vultr High Frequency / Linode Ded. 2–4 vCPU (3.2+ GHz) / 8 GB RAM Local Direct NVMe 2.4M - 3.6M ops/s 75K - 120K ops/s 3,500 - 7,500 tx/s 65K - 100K rec/s 4.8 GB (32 shards)
AWS EC2 t4g.medium / m7g.large 2 vCPU (Graviton2/3) / 4–8 GB EBS gp3 (3,000 IOPS) 1.9M - 3.1M ops/s 60K - 105K ops/s 1,200 - 2,800 tx/s 50K - 85K rec/s 4.5 GB (32 shards)
AWS EC2 i4i.xlarge 4 vCPU (Ice Lake) / 32 GB RAM AWS Nitro Local NVMe 3.2M - 4.8M ops/s 110K - 165K ops/s 8,500 - 16,000 tx/s 90K - 140K rec/s 20 GB (64 shards)
GCP c3-standard-4 / c3d-highmem-4 4 vCPU (Genoa / Emerald) / 16–32 GB Titanium Local SSD 3.5M - 5.2M ops/s 120K - 180K ops/s 9,000 - 18,000 tx/s 95K - 150K rec/s 20 GB (64 shards)
Azure Standard_L8s_v3 8 vCPU (EPYC Milan) / 64 GB RAM Direct Local NVMe 3.0M - 4.5M ops/s 100K - 155K ops/s 8,000 - 15,000 tx/s 85K - 135K rec/s 42 GB (128 shards)
Dedicated Bare-Metal (AX42 / Metal) 8–16 Cores (Ryzen / EPYC) / 64–128 GB Gen4 NVMe RAID-1 4.5M - 7.5M ops/s 150K - 240K ops/s 15,000 - 32,000 tx/s 120K - 200K rec/s 85 GB (128 shards)

vprevail — Consolidated End-User, Administrator & Operations Handbook

vprevail — Distributed In-Memory MVCC & Durable Execution Engine


Part I: vprevail — Distributed System Prevalence, 16-Shard CoW MVCC & Durable Execution Engine

vprevail is a zero-dependency distributed in-memory database, 16-shard Copy-on-Write (CoW) Multi-Version Concurrency Control (MVCC) engine, Restate-style Durable Execution & Virtual Object runtime, and Role-Separated Web Control Plane. Built on the System Prevalence architectural lineage (Klaus Wuestefeld's Prevayler, LMAX Disruptor, Redis/VoltDB, and TigerBeetle), vprevail keeps the entire active dataset in RAM for wait-free nanosecond reads while persisting every mutation sequentially inside an IEEE 802.3 CRC32-verified Write-Ahead Log (.log), 24-byte sparse index (.idx), and non-blocking point-in-time snapshot archive (.snap).


Dual-Persona Overview

For Application Developers & Quant / Platform Engineers

  • Wait-Free Multi-Model MVCC StateSpace: Store dynamic integers, floats, strings, ordered tuples, nested maps, and strongly-typed structured records across isolated logical namespaces without defining boilerplate root graphs.
  • Sub-Microsecond Reads & Instant Time-Travel: Readers check out immutable StateView snapshots in ~20 nanoseconds with zero mutex contention against writers, and query historical state by either logical CommitLog offset or nanosecond Hybrid Logical Clock (HLC) timestamp.
  • Unified State + Durable Workflows: Execute deterministic multi-key transactions (TxBatch), memoized durable workflow steps, non-blocking durable timers, external webhook Awakeable promises, and LIFO Saga compensations inside the exact same atomic CommitLog—eliminating dual-write drift between external workflow orchestrators and databases.
  • Polyglot HTTP/1.1 & SDK Ecosystem: Integrate from any language over /v1/* JSON REST & Server-Sent Events (SSE), or author deterministic durable workflows using the Python, TypeScript/Node.js, Go, and Rust SDKs.

For Site Reliability Engineers, Security Officers & Administrators

  • Self-Healing Crash Recovery & End-to-End CRC32 Integrity: Every storage and replication frame carries a 32-byte VPRV binary header with IEEE CRC32 checksums. Cold startup automatically detects and truncates power-loss torn tail writes while flagging mid-log bit-rot corruption.
  • Online Streaming Telemetry & Counterfactual Replay: Built-in O(1) Welford RunningStats (online Z-scores), 64-register HyperLogLog, BoundedRing buffers, Shannon entropy analyzers, and zero-copy Ephemeral Sandbox WAL Replay let operators backtest risk or SIEM rules against production history without touching live state.
  • Zero-Trust Security & Split-Brain Fencing: Enforces 256-byte padded constant-time bearer/cluster authentication, NIST SP 800-38D AES-256-GCM encryption at rest for workflow SubjectContext identities (with automatic bearer token stripping), and WAL-backed monotonic __system_fencing tokens across shard and Virtual Object migrations.

Role-Separated Web Control Plane Tour (HiDPI Daylight Captures)

vprevail ships a built-in HTTP/1.1 Web Control Plane separated into four role-scoped workspaces (/ui/auth, /ui/portal, /ui/delegated, and /ui/admin).

1. Authentication, Scope Provisioning & QR Pairing Gate (/ui/auth)

Principals authenticate with cluster credentials, request scoped workspace onboarding, or pair mobile/CLI sessions using pure vector ISO/IEC 18004 QR codes.

Authentication and Onboarding Gate

2. Self-Service MVCC Namespace & Time-Travel Studio (/ui/portal)

Authenticated users read, write, expire (TTL), and time-travel across their isolated self:<principal> namespace with {tag} partition-affinity keys.

Portal MVCC Key-Value and Time-Travel Studio

3. Delegated Durable Workflows & Awakeable Approvals (/ui/delegated)

Compliance officers and risk supervisors inspect suspended durable workflows, verify required RBAC roles (compliance:approve), resolve external Awakeable promises, and advance durable timers.

Delegated Durable Workflows and Awakeable Resolution

4. Global Admin Engine, 16-Shard MVCC & Cluster Telemetry (/ui/admin)

Cluster administrators monitor MVCC epochs, CommitLog offsets, monotonic HLC timestamps, 16-shard partition occupancy, fencing terms, and deterministic command execution.

Admin Cluster, MVCC Shards, and WAL Telemetry

5. Ephemeral Sandbox WAL Replay & Version Diff Inspector (/ui/delegated)

Operators fork an isolated zero-copy StateSpace across any historical [from_offset..to_offset] window, measuring microsecond replay latency and inspecting exact key-level state diffs.

Ephemeral Sandbox Replay and Time-Travel Version Inspector

6. Interactive Reference Application Studios (/ui/portal)

Run and audit PrevailBank (double-entry core banking ledger), PrevailAgent (AI agent sandbox with O(1) time-travel undo), PrevailExchange (price-time priority limit order book), and PrevailTwin (Live-to-Sim quant digital twin) directly in the browser.

Reference Application Studios and Double-Entry Ledger


60-Second Quickstart

1. Launch the Control Plane & HTTP/1.1 Gateway

BASH
# Start vprevail on 127.0.0.1:8080 with persistent WAL storage in ./data/prod
./vprevail serve --addr 127.0.0.1:8080 --data-dir ./data/prod --node-id prevail-node-1

Open http://127.0.0.1:8080/ui/auth in your browser to sign into the Self-Service Portal, Delegated Operations Workspace, or Global Administrator Console.

2. Write & Time-Travel Query via REST

BASH
# Mint an authenticated session token
curl -s -X POST http://127.0.0.1:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"principal_id":"admin:root","role":"admin","tenant_id":"tenant:global"}'

# Commit an atomic multi-key TxBatch across namespaces
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "tx-quickstart-01",
    "namespaces": ["wallets", "orders"],
    "keys": ["{acct-1}:usd", "{acct-1}:ord-1001"],
    "deleted": [0, 0],
    "values_json": ["{\"balance_cents\":250000}", "{\"sku\":\"nvme-4tb\",\"qty\":2}"]
  }'

3. Verify On-Disk WAL Integrity & Run Benchmarks

BASH
# Verify IEEE CRC32 checksums across all .log segments, .idx indexes, and .snap files
./vprevail inspect ./data/prod

# Run the quick verification benchmark suite (35 subsystem & reference app workloads)
./vprevail bench --quick

Suite Navigation Guide

Guide Audience Key Topics Covered
How-To Guide Developers Copy-pasteable recipes for REST CRUD, {tag} range scans, time-travel queries, durable workflows, Awakeables, and Python/TS/Go/Rust SDKs.
End-User Guide Portal Users Step-by-step walkthrough of /ui/auth, QR pairing, personal MVCC state, workflow invocations, CDC event streams, and Reference Studios.
Administrator Guide Operators & SREs 16-shard MVCC governance, streaming sketches, sandbox replay, .snap compaction, TCP replication, split-brain fencing, and Zero-Trust TLS/WireGuard.
Operations & Use Cases Architects & SREs Day-2 runbooks, IR-01..IR-05 incident playbooks, and complete guides for PrevailBank, PrevailAgent, PrevailExchange, PrevailTwin, and PulseLedger.
Configuration & CLI Reference All Personas Complete vprevail CLI flags, JSON/TOML runtime configuration schemas, environment variables, and /v1/* + /api/v1/* REST API payloads.
Performance & Sizing Capacity Planners 35-workload empirical benchmarks, Flush Mode durability matrix, RAM sizing formulas, and AWS / GCP / Azure / Hetzner / Bare-Metal projections.
Master User Handbook Offline Readers Consolidated single-volume compilation of all seven End-User, Administrator, and Operations guides.

Part II: vprevail — Developer & Operator How-To Guide

This How-To Guide provides practical, copy-pasteable external recipes for integrating applications and automation pipelines with vprevail via the standalone CLI, the /v1/* HTTP/1.1 JSON & SSE Gateway, and the polyglot durable execution SDKs (Python, TypeScript/Node.js, Go, and Rust).


1. Starting vprevail in Development vs. Production Durability Mode

Fast Buffered Mode (Low-Latency Development & Replicated Clusters)

By default, vprevail appends 32-byte CRC32-framed records sequentially to the OS page cache without blocking every single mutation on a physical disk flush (sync_on_write = false):

BASH
./vprevail serve \
  --addr 127.0.0.1:8080 \
  --data-dir ./data/dev_node \
  --node-id dev-node-1

Strict Per-Commit fsync Mode (--sync + Static Bearer Token)

For single-node financial ledgers requiring strict RPO = 0 survival across sudden host power loss and Zero-Trust API perimeter enforcement, pass --sync and --auth-token:

BASH
./vprevail serve \
  --addr 127.0.0.1:8080 \
  --data-dir ./data/primary \
  --node-id prod-ny4-primary \
  --auth-token "vprv-prod-bearer-9f8e7d6c5b4a3210" \
  --sync

2. Reading, Writing & Expiring Keys with {tag} Partition Affinity

vprevail partitions every namespace across 16 Copy-on-Write shards. Prefixing related keys with {tag} (for example {cust:1001}:profile and {cust:1001}:wallet) routes them to the exact same FNV-1a shard so multi-key writes clone only 1/16th of the namespace and range scans inspect a single shard.

Put a Key with Optional Nanosecond TTL

BASH
# Store a permanent record (ttl_ns = 0)
curl -s -X POST http://127.0.0.1:8080/v1/state/put \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "value_json": "{\"owner\":\"Alice Rivera\",\"balance_cents\":150000,\"tier\":\"PRIME\"}",
    "ttl_ns": 0
  }'

# Store an ephemeral fraud-cooldown lock that expires deterministically after 5 minutes (300e9 ns)
curl -s -X POST http://127.0.0.1:8080/v1/state/put \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "session_locks",
    "key": "{cust:1001}:wire_cooldown",
    "value_json": "{\"locked\":true,\"reason\":\"new_beneficiary\"}",
    "ttl_ns": 300000000000
  }'

Point Lookup & Sorted Prefix / Range Scans

BASH
# Latest wait-free point lookup
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd"
  }'

# Co-located {tag} range scan across a single shard
curl -s -X POST http://127.0.0.1:8080/api/v1/state/range \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "sec_windows",
    "start_key": "{host-01}:20261114T0000",
    "end_key": "{host-01}:20261114T2359"
  }'

3. Executing Atomic Multi-Key Transactions (TxBatch)

To update multiple namespaces and keys with all-or-nothing ACID atomicity (TX_BEGIN .. StateDelta* .. TX_COMMIT), submit a TxBatch:

BASH
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "tx-order-9001",
    "namespaces": ["wallets", "inventory", "orders"],
    "keys": ["{cust:1001}:usd", "sku:nvme-gen5-4tb", "ord:9001"],
    "deleted": [0, 0, 0],
    "values_json": [
      "{\"owner\":\"Alice Rivera\",\"balance_cents\":84200,\"tier\":\"PRIME\"}",
      "{\"warehouse\":\"us-east-va1\",\"available_qty\":19,\"unit_price_cents\":32900}",
      "{\"order_id\":\"ord:9001\",\"customer\":\"cust:1001\",\"qty\":2,\"total_cents\":65800}"
    ]
  }'

4. Performing Wait-Free Time-Travel Audits (By Offset or HLC Timestamp)

Every mutation response returns committed_offset and committed_ts (nanoseconds). Readers can query historical MVCC epochs without locking or slowing down live writers:

BASH
# Query state exactly as it existed at CommitLog offset 12
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "use_at_offset": true,
    "at_offset": 12
  }'

# Query state as of a specific nanosecond Hybrid Logical Clock timestamp
curl -s -X POST http://127.0.0.1:8080/v1/state/get \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "wallets",
    "key": "{cust:1001}:usd",
    "at_timestamp": 1794660496824000000
  }'

5. Invoking Durable Workflows & Resolving External Webhook Awakeables

Durable workflows journal each step in __durable_step so completed side effects are memoized and never re-executed across process restarts or webhook suspensions.

Step 1: Invoke a Workflow That Suspends on an Awakeable Promise

BASH
curl -s -X POST http://127.0.0.1:8080/v1/durable/invoke \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": "exec-wire-swift-501",
    "service_name": "StudioApprovalWorkflow",
    "object_key": "wire:swift-501",
    "input_json": "{\"originator\":\"acct:alice\",\"beneficiary\":\"DEUTDEFF\",\"amount_cents\":2500000}"
  }'

The response includes "status": "suspended_awakeable" and "waiting_awakeable": "exec-wire-swift-501:awake:000001".

Step 2: Resolve the Awakeable from an External Webhook or Compliance Service

BASH
curl -s -X POST http://127.0.0.1:8080/v1/durable/awakeable/resolve \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "awakeable_id": "exec-wire-swift-501:awake:000001",
    "callback_token": "studio-cb-token",
    "payload_json": "{\"approved_by\":\"officer-kim\",\"sanctions_check\":\"PASS\"}",
    "resolver": {
      "principal": {
        "id": "usr:compliance-officer-1",
        "roles": ["compliance:approve"]
      },
      "tenant_id": "tenant:global"
    }
  }'

6. Subscribing to Non-Blocking Real-Time CDC Streams (Poll & SSE)

vprevail includes a non-blocking Change-Data-Capture (CDC) event bus with Drop-Oldest + Lag Watermark backpressure protection so slow downstream consumers never stall the write coordinator.

BASH
# 1. Register a filtered CDC subscription (returns subscriber_id)
curl -s -X POST http://127.0.0.1:8080/v1/events/subscribe \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_filter": "orders",
    "key_prefix": "ord:",
    "max_queue": 512
  }'

# 2. Consume events as a text/event-stream SSE batch
curl -s -X POST http://127.0.0.1:8080/v1/events/stream \
  -H "Authorization: Bearer vprv-prod-bearer-9f8e7d6c5b4a3210" \
  -H "Content-Type: application/json" \
  -d '{"subscriber_id": 1, "max_events": 64}'

7. Authoring Polyglot Durable Workflows (Python, TypeScript, Go & Rust)

External microservices execute deterministic workflow turns via /v1/durable/polyglot/begin and /v1/durable/polyglot/yield using the official zero-dependency client SDKs bundled in release packages under sdk/.

Python Durable Saga Worker

PYTHON
from vprevail_sdk import VPrevailClient, DurableWorkerContext

client = VPrevailClient(
    "http://127.0.0.1:8080",
    auth_token="vprv-prod-bearer-9f8e7d6c5b4a3210",
)

def wire_settlement_saga(ctx: DurableWorkerContext, req: dict) -> dict:
    # Step 0: Reserve funds (memoized in CommitLog; never re-run on replay)
    hold_id = ctx.run("reserve_funds", lambda: f"hold-{req['tx_id']}")
    ctx.compensate(
        "release_funds",
        lambda: client.put("holds_released", hold_id, {"released": True}),
    )

    # Step 1: Non-blocking durable cooling-off timer (50 ms)
    ctx.sleep("settlement_cooldown", duration_ms=50)

    # Step 2: Suspend worker until compliance officer resolves Awakeable
    decision = ctx.awakeable("compliance_signoff")
    if decision != "APPROVED":
        ctx.fail_terminal(f"Compliance rejected transfer: {decision}")

    # Step 3: Commit final settlement receipt
    return ctx.run("commit_transfer", lambda: {"status": "SETTLED", "hold_id": hold_id})

TypeScript / Node.js Durable Saga Worker

TYPESCRIPT
import { VPrevailClient, DurableWorkerContext } from "@vprevail/sdk";

const client = new VPrevailClient({
  baseUrl: "http://127.0.0.1:8080",
  authToken: "vprv-prod-bearer-9f8e7d6c5b4a3210",
});

export async function runOrderFulfillmentSaga(orderId: string) {
  return await client.runPolyglotWorkflow(
    {
      executionId: `exec-${orderId}`,
      serviceName: "OrderSagaService",
      objectKey: orderId,
      input: { orderId, amountCents: 65800 },
    },
    async (ctx: DurableWorkerContext, input: { orderId: string; amountCents: number }) => {
      const reservationId = await ctx.run("reserve_stock", async () => `resv-${input.orderId}`);
      ctx.compensate("release_stock", async () => {
        await client.put("inventory_releases", reservationId, { released: true });
      });

      await ctx.sleep("fraud_window", 25);
      const verdict = await ctx.awakeable<string>("fraud_webhook");
      if (verdict !== "PASS") {
        await ctx.failTerminal("Fraud engine declined order");
      }
      return { status: "FULFILLED", reservationId };
    }
  );
}

Go Durable Saga Worker

GO
package main

import (
	"time"
	"github.com/vprevail/vprevail-go"
)

func RunGoPaymentSaga(client *vprevail.HttpClient, req *vprevail.PolyglotWorkerRequest) (*vprevail.PolyglotWorkerYield, error) {
	return vprevail.ExecuteTurn(req, func(ctx *vprevail.PolyglotContext) (any, error) {
		var holdID string
		if err := ctx.Run("reserve_funds", func() (any, error) {
			return "hold-tx-9001", nil
		}, &holdID); err != nil {
			return nil, err
		}

		ctx.Compensate(func() error {
			_, err := client.Put("holds_released", holdID, map[string]bool{"released": true})
			return err
		})

		if err := ctx.Sleep("settlement_cooldown", 50*time.Millisecond); err != nil {
			return nil, err
		}

		var decision string
		if err := ctx.Awakeable("compliance_signoff", "cb-token-1", "compliance:approve", &decision); err != nil {
			return nil, err
		}
		if decision != "APPROVED" {
			return nil, vprevail.NewTerminalError("compliance rejected wire: " + decision)
		}

		return map[string]string{"status": "SETTLED", "hold_id": holdID}, nil
	})
}

Rust Durable Saga Worker

RUST
use vprevail::{HttpClient, PolyglotContext, VPrevailError};

pub fn run_rust_payment_saga(
    client: &HttpClient,
    ctx: &mut PolyglotContext,
) -> Result<String, VPrevailError> {
    let hold_id = ctx.run("reserve_funds", || Ok("\"hold-tx-9001\"".to_string()))?;

    let release_hold_id = hold_id.clone();
    let host = client.host_port.clone();
    let token = client.auth_token.clone();
    ctx.compensate(move || {
        let comp_cli = HttpClient::new(&host, &token);
        let _ = comp_cli.put_state("holds_released", &release_hold_id, "{\"released\":true}");
    });

    ctx.sleep("settlement_cooldown", 50_000_000)?;

    let decision = ctx.awakeable("compliance_signoff", "cb-token-1", "compliance:approve")?;
    if decision != "\"APPROVED\"" {
        return Err(VPrevailError::Terminal(format!(
            "compliance rejected transfer: {}",
            decision
        )));
    }

    Ok(format!("{{\"status\":\"SETTLED\",\"hold_id\":{}}}", hold_id))
}

Part III: vprevail — End-User Workspace Guide

This End-User Guide walks self-service developers, quant analysts, and domain users through authenticating at /ui/auth and operating the Self-Service Portal (/ui/portal).


1. Signing In, Requesting Onboarding & Pairing via QR (/ui/auth)

Navigate to http://<host>:<port>/ui/auth to access the Authentication & Onboarding Gate.

Authentication and Onboarding Gate

Tab 1: Sign In

  1. Enter your Principal Identifier (for example usr:alice or admin:root) and Display Name.
  2. Choose your Target Workspace Role:
    • portal — Routes to /ui/portal (isolated personal MVCC state, workflow studio, CDC streams, and Reference App Studios).
    • delegated — Routes to /ui/delegated (scoped namespace exploration, streaming sketches, sandbox replay, and Awakeable approvals).
    • admin — Routes to /ui/admin (global engine telemetry, WAL snapshots, cluster replication, and benchmarks).
  3. Enter your Tenant Namespace (for example tenant:quant) and, when the gateway is started with --auth-token, provide the Cluster Bearer Token.
  4. Select desired Session Scopes (state:read, state:write, durable:invoke, events:subscribe, compliance:approve) using the multi-select chip selector and click Authenticate Session.

Tab 2: Request Scoped Access (Onboarding Queue)

If your principal has not yet been provisioned by a tenant operator, switch to Onboarding Request, specify your justification and required scopes, and click Submit Onboarding Request. Your request is written durably to __ui_onboarding for review in /ui/delegated.

Tab 3: ISO/IEC 18004 QR Session Pairing

Switch to QR Session Pairing (or inspect My Profile & Credentials after signing in) to scan a pure-vector 25x25 ISO/IEC 18004 QR code containing an explicit white quiet zone (#ffffff) for reliable camera scanning in both Daylight and Dark themes.


2. Managing Personal MVCC State & Time-Travel (/ui/portal -> My State & Time-Travel)

Every authenticated portal user receives a dedicated, tenant-isolated MVCC namespace (self:<principal_id>) where reads and writes cannot collide with other principals.

Portal MVCC Key-Value and Time-Travel Studio

Writing Permanent & Ephemeral Records

  1. Enter a Key in Key (supports {tag} partition prefix) — for example {treasury}:usd_operating_pool or {acct}:prefs. Using a {tag} prefix co-locates all related keys inside the same MVCC shard.
  2. Set TTL Nanoseconds (0 for permanent persistence, or a positive nanosecond duration such as 3600000000000 for 1 hour).
  3. Enter valid JSON in JSON Value Payload and click Put Record.
  4. Click Inspect JSON on any row in the table to open the formatted keyboard-accessible JSON Lightbox Inspector (Esc to close).

Time-Travel Point-in-Time Inspection

  1. Note the Updated Offset column on earlier versions of your keys.
  2. Enter any historical CommitLog offset into Time-Travel Offset (0 = latest) (for example 8) and click Query / Time-Travel Scan.
  3. The portal checks out an immutable historical StateView from the MVCC ring buffer in O(1) without locking or affecting concurrent writes. Reset Time-Travel Offset to 0 to return to the live head epoch.

3. Invoking Durable Workflows & Inspecting Step Journals (/ui/portal -> My Workflows & Awakeables)

Switch to My Workflows & Awakeables to launch stateful Virtual Objects and Restate-style durable workflows:

  1. Set a unique Execution ID (for example exec-portal-101), Service Name (StudioEchoWorkflow for immediate completion, or StudioApprovalWorkflow to test external webhook suspension), and Virtual Object Key (obj:user-1).
  2. Provide Input JSON and click Invoke Durable Workflow.
  3. Click Inspect Steps on any execution row to view the persisted __durable_step memoization journal, retry attempt count, registered Saga compensations, and waiting Awakeable ID.

4. Streaming Real-Time CDC Events (/ui/portal -> My Event Subscriptions)

Switch to My Event Subscriptions to observe live mutations across namespaces:

  1. Optionally enter a Namespace Filter (such as studio_bank_ledger or leave empty for all namespaces) and a Key Prefix Filter (such as wire-).
  2. Click Create Subscription to allocate a bounded non-blocking subscriber ring (max_queue = 256).
  3. Trigger writes in another tab (or in Reference App Studios), then click Poll Events (/v1/events/poll) to populate the table or Fetch SSE Stream (/api/v1/events/stream) to inspect the raw text/event-stream wire batch.
  4. Click Unsubscribe when finished to release the subscriber slot cleanly.

5. Exploring Interactive Reference Application Studios (/ui/portal -> Reference App Studios)

The Reference App Studios sub-tab lets you interactively drive four domain reference architectures directly against the live PrevalentEngine:

Reference Application Studios and Double-Entry Ledger

Studio Selection Primary / Counterparty Parameters Interactive Actions
PrevailBank — Double-Entry Core Banking & Wire Ledger Originator (acct:alice), Beneficiary (acct:bob), Amount in cents (25000) 1. Seed Baseline State initializes asset/liability accounts; 2. Execute App Scenario posts balanced DEBIT + CREDIT legs summing strictly to zero.
PrevailAgent — AI Agent Sandbox & O(1) Time-Travel Undo Patch target (file:firewall.conf), Candidate content, Revision 2. Execute App Scenario applies an autonomous sandbox mutation; 3. Time-Travel Undo restores exact pre-mutation state from historical MVCC offset.
PrevailExchange — Price-Time Priority CLOB & Prediction Market Order side (BID or ASK), Symbol, Limit price in cents (55) 1. Seed Baseline State posts resting maker liquidity; 2. Execute App Scenario crosses or rests limit orders with integer collateral conservation.
PrevailTwin — Live-to-Sim Quant Digital Twin & Circuit Breaker Branch profile, Counterparty, Volatility shock in bps (380) 2. Execute App Scenario forks two parallel simulation branches (Twin-A conservative vs. Twin-B aggressive) and evaluates drawdown circuit breakers.

6. Theme Switching & Keyboard Accessibility

  • Daylight / Dark Theme Toggle: Click the Light / Dark toggle button in the top navigation bar to switch between Daylight Paper & Slate (data-theme="light", default) and Dark Mode (data-theme="dark"). Your preference persists in localStorage.
  • Keyboard Shortcuts: All sub-tabs, multi-select chips, and Inspect JSON modals are keyboard-navigable (Tab, Enter, and Escape to dismiss any open Lightbox modal).

Part IV: vprevail — Administrator & Security Operator Guide

This Administrator Guide covers day-to-day governance of vprevail clusters using the Delegated Operations Workspace (/ui/delegated), the Global Administrator Console (/ui/admin), and Zero-Trust production deployment topologies.


1. Delegated Operations Workspace (/ui/delegated)

Operators with the delegated or admin role use /ui/delegated to manage tenant namespaces, run online anomaly sketches, replay WAL windows in an isolated sandbox, and approve suspended workflows.

1.1 Tenant Namespaces, {tag} Range Scans & Dynamic Tuples

  • Prefix & Range Explorer: Query any namespace at the latest head (At Offset = 0) or any retained historical offset. Supplying a {tag} prefix (such as {deskA}:) restricts sorted range scans to a single FNV-1a shard.
  • Atomic Multi-Key TxBatch & Tuples: Commit multi-record TX_BEGIN .. TX_COMMIT batches or schema-less dynamic Tuples directly from the operator console, and run targeted Reap Expired TTLs sweeps per namespace.

1.2 Streaming Sketches & Online Anomaly Detection

The Streaming Sketches & Telemetry sub-tab exposes four deterministic constant-memory primitives designed for high-velocity SIEM and financial telemetry:

  1. RunningStats (Welford Variance & EWMA Z-Score): Computes streaming count, mean, sample standard deviation, exponentially weighted moving average (EWMA), and instant anomaly Z-scores in O(1) RAM (40 bytes per metric).
  2. 64-Register HyperLogLog: Estimates distinct cardinality (such as unique source IPs or trading accounts) in 64 bytes of state.
  3. BoundedRing Circular Buffers: Retains the most recent N observations per entity with deterministic oldest-item eviction.
  4. Shannon Entropy Analyzer: Computes payload entropy in bits/byte (0.0 .. 8.0) to flag obfuscated scripts, base64-encoded exfiltration, or high-entropy anomalies.

1.3 Ephemeral Sandbox WAL Replay & Backtesting

Ephemeral Sandbox Replay and Time-Travel Version Inspector

In Sandbox Replay & Backtesting, enter a [From Offset .. To Offset] window and click Run Ephemeral Sandbox Replay. vprevail forks a zero-copy Copy-on-Write StateSpace without acquiring writer locks on production traffic, replays the historical CommitLog window, reports replay latency in microseconds, and lists every key diff (added, modified, deleted).

1.4 Awakeable Webhook Approvals & Onboarding Review

Delegated Durable Workflows and Awakeable Resolution

  • Durable Approvals & Timers: Click Select on any waiting Awakeable promise to populate its ID, verify the callback token and JSON approval payload, and click Resolve Awakeable (or Advance Durable Timers to trigger due sleep steps).
  • Onboarding Requests: Switch to Onboarding Requests to approve or reject pending access requests submitted via /ui/auth. Approving a request automatically provisions the principal policy in __ui_principals.

2. Global Administrator Console (/ui/admin)

Admin Cluster, MVCC Shards, and WAL Telemetry

2.1 Engine & 16-Shard MVCC Governance

Monitor the five core prevalence indicators in real time:

  • Node / Gateway ID: Active logical node and HTTP gateway identifiers.
  • MVCC Epoch: Monotonically increasing published StateSpace generation counter.
  • Committed / Next Offset: Highest durable CommitLog record offset vs. next allocatable sequence number.
  • PrevalentClock (ns): Current monotonic Hybrid Logical Clock watermark.
  • Retained History: Active historical StateView count vs. configured ring capacity (max_version_history).

The MVCC Namespace & 16-Shard Partition Inventory table displays entry counts, active shards (k / 16), and current __system_fencing terms for every user and internal namespace (__durable_exec, __durable_step, __durable_awake, __system_fencing).

2.2 CommitLog, Non-Blocking .snap Checkpoints & Segment Compaction

Switch to CommitLog, Snapshots & Inspector to manage disk lifecycle safely:

  1. Create .snap Checkpoint: Serializes the current immutable StateView to an atomic CRC32-verified snapshot file without pausing live writes, pruning older snapshots beyond keep_latest.
  2. Run CRC32 WAL Inspector: Scans every .snap and .log segment on disk, verifying all 32-byte VPRV headers, IEEE CRC32 checksums, and TX_BEGIN / TX_COMMIT / TX_ABORT counts.
  3. Truncate Old Rolled Segments: Deletes rolled .log and .idx segments whose maximum offset is strictly less than a verified .snap checkpoint offset. The active head segment is never deleted.

2.3 Cluster Replication & Split-Brain Shard Fencing

Switch to Cluster Replication & Shard Mobility to execute:

  • Ping Peer: Verify authenticated TCP reachability and constant-time cluster_secret match against a remote peer.
  • Pull Log From Peer: Pull and deterministically replay committed WAL frames from a primary node.
  • Push Namespace To Peer: Transfer an entire namespace (wrapped in TX_BEGIN .. TX_COMMIT) to a target node.
  • Advance Local Shard Fencing Term: Increment the WAL-persisted __system_fencing epoch for a namespace or specific shard (0..15) before migrating ownership so stale writers are deterministically rejected.

2.4 Durable Journal Compaction & Zero-Trust Policy Provisioning

  • Compact Completed Journals (admin-durable): Prunes historical __durable_exec, __durable_step, __durable_timer, and __durable_awake keys for terminal executions (completed, failed_terminal, cancelled) older than a cutoff timestamp to keep active RAM lean.
  • Principal Policy Provisioning (admin-security): Provision multi-role principals (admin, delegated, portal, compliance:approve, risk:evaluate) and audit active defense-in-depth enforcement across all subsystems.

3. Production Zero-Trust Network & Systemd Deployment

vprevail intentionally keeps TLS/mTLS termination and kernel tunnel encryption outside its pure-V memory space to eliminate OpenSSL CVE surface area. In production:

  1. Bind Listeners to Loopback or Encrypted Mesh Interfaces: Bind --addr 127.0.0.1:8080 behind an mTLS reverse proxy (Caddy, Envoy, or NGINX) or bind to a private WireGuard interface (10.200.0.1:8080).
  2. Always Configure Non-Empty Secrets: Pass a high-entropy 32+ byte --auth-token (256 bits of CSPRNG entropy) in production.
  3. Dedicated NVMe Volume: Mount --data-dir ./data on local NVMe storage (ext4 or xfs with noatime) and reserve 30% free disk headroom for segment rolling and .snap atomic renames.

Reference Linux systemd Unit (deploy/vprevail.service)

INI
[Unit]
Description=vprevail Distributed System Prevalence & Durable Execution Engine
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vprevail
Group=vprevail
WorkingDirectory=./data
EnvironmentFile=/etc/vprevail/vprevail.env
ExecStart=./vprevail serve --config /etc/vprevail/vprevail.json
Restart=on-failure
RestartSec=3s
TimeoutStopSec=15s
KillSignal=SIGTERM
LimitNOFILE=65536
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=./data

[Install]
WantedBy=multi-user.target

Part V: vprevail — Operations Runbooks & Reference Application Use Cases

This guide combines Day-2 Operational & Incident Response Runbooks with complete architectural walkthroughs and external execution examples for vprevail's five domain applications (PrevailBank, PrevailAgent, PrevailExchange, PrevailTwin, and PulseLedger) plus distributed cluster topologies (PrevailFlow, PrevailKV, and PrevailMetrics).


1. Day-2 Operational Runbooks & Self-Healing IR Playbooks

1.1 Automated Self-Healing Matrix

Fault / Anomaly Built-In Self-Healing Mechanism Operator Verification
Power-Loss Torn Tail Frame Cold startup scans the active .log segment, detects partial trailing header/body bytes, truncates cleanly to the last verified IEEE CRC32 frame boundary, and discards uncommitted TX_BEGIN batches. Run ./vprevail inspect <data_dir> and confirm Total WAL Frames equals Committed plus balanced transaction markers.
Missing or Truncated .idx File Startup automatically reconstructs the 24-byte sparse offset/timestamp index by scanning verified frames in the corresponding .log segment. Zero downtime; verify segment count via /api/v1/wal/inspect.
NTP Backward Wall-Clock Jump PrevalentClock CAS loop refuses to move backward, incrementing the logical nanosecond counter monotonically until wall time catches up. Check PrevalentClock (ns) in /ui/admin (admin-engine).
Slow or Disconnected CDC Consumer Bounded subscriber ring evicts oldest unread notifications (Drop-Oldest) and increments dropped_count + min_retained_offset watermark without stalling commits. Poll /v1/events/poll and trigger incremental scan catch-up if dropped_count > 0.
Transient Downstream API Timeout Durable run_with_retry applies bounded exponential backoff while preserving memoized prior steps. Inspect attempt counts in /ui/admin (admin-durable).

1.2 Incident Response Playbooks (IR-01 through IR-05)

IR-01: Mid-Log CRC32 Bit-Rot Alert

  • Symptom: Startup or ./vprevail inspect reports a CRC32 mismatch inside a non-tail frame (caused by faulty NVMe flash or uncorrectable storage bit-rot).
  • Resolution:
  1. Do not overwrite the affected directory; archive it for hardware diagnostics.
  2. Provision a clean --data-dir on healthy NVMe media.
  3. Restore the latest verified .snap checkpoint from backup or pull committed history from an online replica via /api/v1/cluster/op (pull_log).

IR-02: Split-Brain / Stale Primary After Network Partition

  • Symptom: A partitioned primary node comes back online after Virtual Object or shard ownership was migrated to a standby peer.
  • Resolution:
  1. On the authoritative target node, verify that __system_fencing holds the higher monotonic fencing term via /ui/admin (admin-cluster -> Check Fencing Term).
  2. Advance the fencing term on the decommissioned primary before reconnecting it as a read-only consumer replica. Any stale local write or timer resumption on the old primary is deterministically rejected.

IR-03: Unbounded Disk Growth on High-Write Node

  • Symptom: Rolled .log segments accumulate on ./data.
  • Resolution:
  1. Confirm all async replicas have pulled past the target offset.
  2. Trigger a non-blocking .snap checkpoint:
BASH
     curl -s -X POST http://127.0.0.1:8080/api/v1/wal/snapshot \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
       -d '{"keep_latest": 3}'
  1. Truncate rolled segments strictly older than the returned snapshot offset:
BASH
     curl -s -X POST http://127.0.0.1:8080/api/v1/wal/compact \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
       -d '{"min_offset": 50000}'

IR-04: Suspended Durable Workflows Awaiting Compliance Sign-Off

  • Symptom: High count of suspended_awakeable executions in /ui/delegated.
  • Resolution: Review pending Awakeables in /ui/delegated (delegated-durable) and either resolve with an authorized compliance:approve principal or cancel terminal stale executions via /api/v1/durable/manage ({"action":"cancel","execution_id":"..."}), which automatically runs registered LIFO Saga compensations.

IR-05: High RAM Utilization from Completed Workflow Journals or Expired Keys

  • Resolution: Trigger global TTL reaping (/api/v1/state/reap) and prune completed durable step journals (/api/v1/durable/manage with {"action":"compact_before"}).

2. Reference Application #1: PrevailBank (Core Banking & Double-Entry General Ledger)

PrevailBank models an institutional core banking ledger and cross-border SWIFT wire settlement pipeline where every financial mutation posts balanced Debit (-cents) and Credit (+cents) legs summing strictly to zero across every MVCC epoch.

Key Architectural Mechanics

  • Two-Phase Funds Reservation: Initiating an international wire places funds into held_cents (available_cents = balance_cents - held_cents) and registers a LIFO Saga compensation (release_wire_hold) before invoking external sanctions screening.
  • Unified Ledger + Workflow WAL: Sanctions retries, cooling-off timers, compliance officer Awakeables, and general-ledger postings commit to the exact same CommitLog, eliminating dual-write drift.
  • Encrypted Principal Context: Customer and compliance identities are sealed at rest using NIST SP 800-38D AES-256-GCM with execution_id AAD binding, while ephemeral bearer tokens are stripped prior to disk persistence.

Running & Querying PrevailBank

BASH
# Run the standalone compiled PrevailBank reference binary (6-stage end-to-end banking simulation)
./dist/bin/windows/banking_ledger.exe   # Windows
./dist/bin/linux/banking_ledger         # Linux

# Or drive PrevailBank live over REST via the Gateway Studio endpoint:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "bank",
    "action": "execute",
    "param_a": "acct:alice",
    "param_b": "acct:bob",
    "amount": 42500,
    "target_offset": 1
  }'

3. Reference Application #2: PrevailAgent (Autonomous AI Agent Sandbox & O(1) Undo)

PrevailAgent provides a deterministic guardrail runtime for autonomous coding, infrastructure, and security response agents.

Key Architectural Mechanics

  • Zero-Rebilling LLM Step Memoization: Expensive LLM tool-planning turns execute inside memoized durable steps. If an agent pauses for human approval or restarts after a crash, prior token-billed LLM responses are replayed instantly from the WAL at zero API cost.
  • Human-in-the-Loop Awakeable Gate: High-impact mutations (such as firewall policy edits or production deployments) suspend automatically on an Awakeable until an operator with the required RBAC role approves or rejects the diff.
  • O(1) Time-Travel Workspace Undo: Every agent tool patch records its pre-patch CommitLog offset, enabling instant point-in-time state restoration or LIFO Saga rollback if post-patch validation fails.

Running & Querying PrevailAgent

BASH
# Run the standalone compiled PrevailAgent reference binary
./dist/bin/windows/agent_sandbox.exe    # Windows
./dist/bin/linux/agent_sandbox          # Linux

# Execute a sandboxed agent patch and trigger O(1) Time-Travel Undo via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "agent",
    "action": "undo",
    "param_a": "policy:prod_egress",
    "param_b": "v1_baseline",
    "amount": 1,
    "target_offset": 1
  }'

4. Reference Application #3: PrevailExchange (Sub-Microsecond CLOB & Prediction Market)

PrevailExchange implements a deterministic Central Limit Order Book (CLOB) and binary prediction market matching engine inspired by LMAX Disruptor and Polymarket/Kalshi settlement pipelines.

Key Architectural Mechanics

  • Single-Writer Price-Time Priority (FIFO): Serializing order matching on the single-writer PrevalentEngine eliminates lock contention on hot price levels while delivering sub-microsecond matching determinism.
  • Strict Integer Collateral Conservation: Escrowed trader collateral plus settled payouts is conserved to the exact integer cent across partial fills, maker price-improvement refunds, cancellations, and oracle market resolution.
  • Wait-Free Level-2 Market Data: Market-data feeds read immutable StateView order-book snapshots concurrently without delaying order matching by a single nanosecond.

Running & Querying PrevailExchange

BASH
# Run the standalone compiled PrevailExchange reference binary
./dist/bin/windows/exchange_matching.exe  # Windows
./dist/bin/linux/exchange_matching        # Linux

# Submit an immediate-crossing BID limit order at 55 cents via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "exchange",
    "action": "execute",
    "param_a": "BID",
    "param_b": "MKT-FED-RATE",
    "amount": 55,
    "target_offset": 1
  }'

5. Reference Application #4: PrevailTwin (Live-to-Sim Quant Digital Twin)

PrevailTwin eliminates "Live-to-Sim" code skew in algorithmic trading and risk engineering by running the exact same deterministic command handlers across live market ingestion and forked counterfactual simulations.

Key Architectural Mechanics

  • Zero-Copy Counterfactual Forking: Forks Twin-A (conservative risk-off flatten) and Twin-B (aggressive momentum) directly from a live production MVCC epoch at near-zero memory cost.
  • Volatility Circuit-Breaker Sagas & TWAP Fast-Forwarding: Evaluates online EWMA volatility shocks (bps), trips circuit-breaker Sagas automatically when drawdown thresholds are breached, and fast-forwards multi-slice TWAP execution timers deterministically in replay time.

Running & Querying PrevailTwin

BASH
# Run the standalone compiled PrevailTwin reference binary
./dist/bin/windows/trading_twin.exe     # Windows
./dist/bin/linux/trading_twin           # Linux

# Fork a 420 bps volatility shock counterfactual simulation via REST:
curl -s -X POST http://127.0.0.1:8080/api/v1/apps/scenario \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "twin",
    "action": "execute",
    "param_a": "desk:stat-arb",
    "param_b": "shock-420bps",
    "amount": 420,
    "target_offset": 1
  }'

6. Reference Application #5: PulseLedger (Flash-Sale E-Commerce & Fulfillment)

PulseLedger demonstrates hybrid multi-model storage during high-concurrency retail flash sales by combining three storage representations inside a single atomic transaction:

  1. wallets Namespace (Integer Values): Customer spending balances in minor currency units (cents).
  2. inventory Namespace (Dynamic Tuples): Compact positional tuples [product_title, warehouse_zone, available_qty, unit_price_cents].
  3. orders Namespace (Structured Receipts): Numbered order tickets stamped with deterministic PrevalentClock timestamps and CommitLog offsets, paired with a role-gated (orders:ship) durable carrier-label fulfillment workflow and async replica catch-up.
BASH
# Execute an atomic flash-sale checkout across wallets, inventory, and orders via REST:
curl -s -X POST http://127.0.0.1:8080/v1/tx/batch \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tx_id": "pulse-flash-ord-9001",
    "namespaces": ["wallets", "inventory", "orders"],
    "keys": ["cust:alice", "sku:nvme-2tb", "ord:9001"],
    "deleted": [0, 0, 0],
    "values_json": [
      "{\"balance_cents\":20000}",
      "[\"Gen4 NVMe 2TB SSD\",\"us-east-rack-4\",8,15000]",
      "{\"order_id\":\"ord:9001\",\"customer_id\":\"cust:alice\",\"sku\":\"sku:nvme-2tb\",\"qty\":2,\"total_cents\":30000}"
    ]
  }'

7. Distributed Cluster Blueprints (PrevailFlow, PrevailKV, PrevailMetrics)

Blueprint Primary Workload Recommended vprevail Configuration
PrevailFlow Geo-distributed durable workflow & Virtual Object actor mesh Enable AES-256-GCM SubjectContext sealing, configure two-tier remote durable tokens, and advance __system_fencing epochs prior to live Virtual Object migration across regions.
PrevailKV Multi-region low-latency configuration, session & feature-flag store Partition tenant keys with {tenant_id}: affinity tags across 32 or 64 shards, run continuous PullReplicator read replicas per availability zone, and snapshot hourly.
PrevailMetrics / PrevailSec High-velocity SIEM correlation, IoT telemetry & anomaly detection Use {host_id}: co-located time windows with deterministic ttl_ns watermarks, maintain RunningStats + HyperLogLog sketches in RAM, and backtest detection rules via /api/v1/sandbox/replay.

Part VI: vprevail — Configuration, CLI & REST API Reference

This reference documents all standalone vprevail CLI commands and flags, reference binary executables, engine/cluster/durable/gateway configuration parameters, and HTTP/1.1 JSON & SSE endpoints.


1. Standalone vprevail CLI Reference

TEXT
vprevail 1.0.0 — Pure-V Distributed System Prevalence, MVCC & Durable Execution Engine

Usage:
  vprevail <command> [options]

Commands:
  serve, ui                    Start the HTTP/1.1 Gateway, optional Cluster TCP node & Web Control Plane
  bench                        Execute the 35-workload subsystem & reference app benchmark suite
  inspect <dir>                Verify IEEE CRC32 WAL segments (.log), sparse indexes (.idx), & snapshots (.snap)
  snapshot <dir>               Recover state in <dir> and write a verified atomic .snap checkpoint
  compact <dir> <min_offset>   Truncate rolled WAL segments strictly older than <min_offset>
  version                      Print the vprevail engine version
  help                         Display this CLI reference

vprevail serve / vprevail ui Flags & Environment Variables

Flag Environment Variable Default Description
--config <path> VPREVAIL_CONFIG "" Load JSON configuration manifest (e.g., config/vprevail.example.json).
--addr <host:port>, -a VPREVAIL_ADDR 127.0.0.1:8080 TCP bind address and port for the HTTP/1.1 Gateway & Web Control Plane (16 KiB header cap, 4 MiB body cap).
--data-dir <path>, -d VPREVAIL_DATA_DIR data/ui_studio Directory storing .log segments, .idx sparse indexes, and .snap checkpoints.
--auth-token <secret> VPREVAIL_AUTH_TOKEN "" (fail-closed) Static Zero-Trust Bearer token verified via 256-byte padded constant-time comparison (prefer env var over CLI arg).
--node-id <id> VPREVAIL_NODE_ID studio-node-1 Logical node identifier stamped onto health, overview, and mutation responses.
--cluster-addr <host:port> VPREVAIL_CLUSTER_ADDR "" Enables the ClusterNode binary TCP replication listener on <host:port>.
--cluster-secret <secret> VPREVAIL_CLUSTER_SECRET "" Shared inter-node authentication secret (prefer env var over CLI arg).
--read-only-follower VPREVAIL_READ_ONLY_FOLLOWER false Rejects direct client write RPCs on ClusterNode to prevent split-brain writes.
--sync VPREVAIL_SYNC false Forces an OS fsync / _commit barrier on every CommitLog frame/batch write (RPO = 0 durability).
--structured-logs VPREVAIL_STRUCTURED_LOGS false Emits JSON access and security audit logs to stderr.
--cookie-secure VPREVAIL_COOKIE_SECURE false Adds the Secure attribute to HttpOnly; SameSite=Strict session cookies (enable behind TLS).
--studio-demo VPREVAIL_STUDIO_DEMO false Registers built-in Studio demo workflows (StudioEchoWorkflow, StudioApprovalWorkflow).
--allow-insecure-dev VPREVAIL_ALLOW_INSECURE_DEV false Permits unauthenticated Studio login when auth_token is empty (local development only).
(env/config only) VPREVAIL_ENCRYPTION_KEY_HEX "" Optional 64-hex-char (32-byte) AES-256-GCM key sealing SubjectContext records at rest.

vprevail bench & vprevail inspect Flags

Command & Flag Description
vprevail bench Runs all 35 empirical subsystem, codec, MVCC, cluster, durable, polyglot, and SIEM benchmarks at full production iteration counts and prints the cloud sizing table.
vprevail bench --quick (-q) Runs fast verification iteration counts across all 35 workloads (~1–2 seconds).
vprevail inspect <data_dir> Scans all .snap checkpoints and .log segments in <data_dir>, verifying every 32-byte VPRV header and IEEE CRC32 checksum without mutating state.

Bundled Reference Application Executables (dist/bin/<platform>/)

Executable Domain Description
vprevail / vprevail.exe Core Server & CLI Standalone HTTP/1.1 Gateway, 4-workspace Web UI Control Plane, WAL inspector, and benchmark runner.
banking_ledger / .exe Core Banking Runs the 6-stage PrevailBank double-entry ledger, SWIFT wire hold, Awakeable approval, snapshot, and fenced migration suite.
agent_sandbox / .exe AI Agent Guardrails Runs the 6-stage PrevailAgent memoized LLM tool-use, human-in-the-loop gate, O(1) time-travel undo, and migration suite.
exchange_matching / .exe Financial Exchange Runs the 6-stage PrevailExchange price-time FIFO limit order book, collateral conservation, and oracle settlement suite.
trading_twin / .exe Quant Digital Twin Runs the 6-stage PrevailTwin Live-to-Sim counterfactual fork, volatility circuit-breaker Saga, and TWAP fast-forward suite.

2. Runtime Configuration Reference (JSON / TOML Parameters)

When embedding or configuring vprevail services via structured deployment manifests, the four subsystem configuration blocks expose the following parameters:

2.1 Engine & MVCC Configuration (engine)

Parameter Type Default Description
node_id string "node-1" Unique logical identifier for this PrevalentEngine instance.
data_dir string "./data" Filesystem path for .log, .idx, and .snap persistence.
default_codec string "msgpack_map" Default serialization format: "msgpack_tuple", "msgpack_map", "json", or "raw_bytes".
sync_on_write bool false When true, flushes OS buffers to non-volatile storage on every WAL append/commit.
max_segment_bytes i64 67108864 (64 MiB) Maximum active .log segment size before rolling to a new zero-padded segment file.
index_interval_bytes i64 4096 (4 KiB) Byte stride between 24-byte sparse .idx entries (offset, file_pos, timestamp).
shard_count int 16 Number of FNV-1a Copy-on-Write shards per namespace (16, 32, 64, or 128).
max_version_history int 64 (128 in UI) Number of historical MVCC StateView epochs retained in the in-memory time-travel ring.

2.2 Cluster Transport Configuration (cluster)

Parameter Type Default Description
listen_addr string "127.0.0.1:9100" TCP bind address for inter-node WAL replication and subgraph transfers.
cluster_secret string (required) Shared peer authentication secret compared in constant time (padded to 256 bytes).
io_timeout_ms int 5000 Read/write TCP socket deadline per RPC frame (4 MiB max RPC payload cap).

2.3 Durable Execution Configuration (durable)

Parameter Type Default Description
default_codec string "msgpack_tuple" Default journal codec for step outputs and Virtual Object state.
encryption_key_hex string "" Optional 64-hex-char (32-byte) AES-256-GCM master key sealing SubjectContext records at rest.
max_retry_attempts int 3 Default retry ceiling for transient step failures in run_with_retry.

2.4 HTTP/1.1 Gateway Configuration (gateway)

Parameter Type Default Description
gateway_id string "gateway-1" Identifier included in /v1/health and QR pairing URIs.
listen_addr string "127.0.0.1:8080" HTTP/1.1 TCP bind address (16 KiB header cap, 4 MiB body cap). Unauthenticated probes exposed at /healthz, /readyz, and /metrics.
auth_token string "" Optional static Bearer token required alongside or in place of UI session tokens.

Example Deployment Configuration (vprevail.toml)

TOML
[engine]
node_id = "prod-eu-central-1"
data_dir = "./data"
default_codec = "msgpack_map"
sync_on_write = true
max_segment_bytes = 67108864
index_interval_bytes = 4096
shard_count = 32
max_version_history = 128

[cluster]
listen_addr = "10.200.0.11:9100"
cluster_secret = "replace-with-32-byte-csprng-cluster-secret"
io_timeout_ms = 5000

[durable]
default_codec = "msgpack_tuple"
max_retry_attempts = 5

[gateway]
gateway_id = "prod-eu-central-1-gw"
listen_addr = "127.0.0.1:8080"
auth_token = "replace-with-32-byte-csprng-gateway-token"

3. Complete HTTP/1.1 REST & Control-Plane API Reference

3.1 Public Browser & Authentication Endpoints

Method Path Description
GET /, /ui, /ui/auth Renders the Authentication, Scope Onboarding & ISO 18004 QR Pairing Gate.
GET /ui/portal Renders the End-User Self-Service Portal workspace.
GET /ui/delegated Renders the Scoped / Delegated Operations workspace.
GET /ui/admin Renders the Global Administrator Console workspace.
GET /ui/docs Serves the rendered End-User HTML Documentation Suite (dist/docs/user/index.html).
GET /logo.svg, /icon.svg Serves pure-vector brand assets with image/svg+xml caching headers.
POST /api/v1/auth/login Authenticates a principal and mints a vprv_sess_* session token + Set-Cookie.
POST /api/v1/auth/register Submits a scoped access request into __ui_onboarding.
POST /api/v1/auth/logout Revokes the active session token from __ui_sessions.

3.2 Core Data-Plane, Durable & CDC Endpoints (Bearer Auth Required)

Method Path Key Request Fields Description
GET /v1/health (none) Returns status, gateway_id, node_id, epoch, last_offset, and next_offset.
POST /v1/state/get namespace, key, at_offset, at_timestamp Wait-free live or historical point lookup.
POST /v1/state/put namespace, key, value_json, ttl_ns Writes a JSON record with optional deterministic nanosecond TTL.
POST /v1/state/delete namespace, key Atomically deletes a key and records a StateDelta tombstone in the WAL.
POST /v1/state/scan namespace, prefix, max_items, at_offset Sorted prefix scan across live or historical MVCC state.
POST /v1/tx/batch tx_id, namespaces, keys, deleted, values_json Commits an atomic multi-namespace TX_BEGIN .. TX_COMMIT batch.
POST /v1/commands/execute cmd_name, payload_json Executes a registered deterministic CommandHandler on the coordinator.
POST /v1/durable/invoke execution_id, service_name, object_key, input_json Invokes or resumes a durable workflow / Virtual Object.
POST /v1/durable/awakeable/resolve awakeable_id, callback_token, payload_json, resolver Resolves a suspended Awakeable promise under RBAC verification.
POST /v1/durable/polyglot/begin execution_id, service_name, object_key, input_json Starts or replays a polyglot SDK workflow turn, returning memoized step history.
POST /v1/durable/polyglot/yield execution_id, yield_kind, steps, output_json Commits new steps, timers, Awakeables, or terminal output from an external SDK worker.
POST /v1/events/subscribe namespace_filter, key_prefix, max_queue Registers a non-blocking CDC event stream subscriber.
POST /v1/events/poll subscriber_id, max_events Polls queued CDC mutation events in JSON format.
POST /v1/events/stream subscriber_id, max_events Streams queued CDC events in text/event-stream (SSE) format.
POST /v1/events/unsubscribe subscriber_id Releases an active CDC subscriber ring buffer.

3.3 Operator & Control-Plane Telemetry Endpoints (Bearer Auth Required)

Method Path Description
GET /api/v1/self/session Returns active principal profile, roles, scopes, latest offset, and session QR SVG.
POST /api/v1/self/state Isolated put / list / delete + time-travel scan inside self:<principal>.
GET /api/v1/engine/overview Returns live MVCC epoch, HLC timestamp, retained versions, and 16-shard namespace table.
GET /api/v1/wal/inspect Runs full IEEE CRC32 diagnostic inspection across .log and .snap files.
POST /api/v1/wal/records Reads decoded WAL frame headers and payload sizes starting from from_offset.
POST /api/v1/wal/snapshot Creates a non-blocking .snap checkpoint and prunes older snapshots (keep_latest).
POST /api/v1/wal/compact Truncates rolled .log/.idx segments strictly older than min_offset.
POST /api/v1/cluster/op Runs ping, pull_log, push_namespace, fencing_advance, or fencing_get.
POST /api/v1/sandbox/replay Forks an ephemeral zero-copy StateSpace, replays [from_offset..to_offset], and returns key diffs.
POST /api/v1/sketches/stats Updates Welford RunningStats + EWMA and evaluates online anomaly Z-scores.
POST /api/v1/sketches/hll Updates 64-register HyperLogLog cardinality estimators.
POST /api/v1/sketches/ring Pushes items into a BoundedRing circular telemetry buffer.
POST /api/v1/sketches/entropy Computes Shannon entropy (bits/byte) on candidate command/payload strings.
POST /api/v1/apps/scenario Executes interactive seed, execute, and undo scenarios across the 4 Reference Studios.
POST /api/v1/admin/bench Runs live in-process codec, MVCC checkout, and streaming sketch micro-benchmarks.

Part VII: vprevail — Performance Benchmarks & Cloud Sizing Guide

This guide presents empirical subsystem and workload measurements from vprevail bench (-prod optimized builds), explains durability flush trade-offs, compares vprevail against external storage engines, and provides RAM capacity formulas and cloud instance sizing projections.


1. Executive Throughput & Latency Summary

Measured on an 8-core x86_64 workstation with local Gen4 NVMe storage using ./vprevail bench:

Architectural Stratum Representative Workload Measured Throughput Latency (ns/op or us/op)
1. Wire Framing & Codecs MsgPack Tuple Encode + 32B CRC32 Frame + Decode 1,380,000+ ops/s ~720 ns (148 B wire frame)
1. Wire Framing & Codecs MsgPack Map Encode + 32B CRC32 Frame + Decode 980,000+ ops/s ~1.02 us (214 B wire frame)
1. Wire Framing & Codecs JSON RFC 8259 Encode + 32B CRC32 Frame + Decode 640,000+ ops/s ~1.56 us (256 B wire frame)
2. 16-Shard CoW MVCC Wait-Free StateView Checkout + Typed Point Lookup 6,800,000+ ops/s ~145 ns (zero reader locks)
2. 16-Shard CoW MVCC Pure In-Memory Dirty-Shard CoW {tag} Mutation 3,850,000+ ops/s ~258 ns (1/16 shard clone)
2. 16-Shard CoW MVCC Historical view_at_offset Time-Travel Lookup 5,200,000+ ops/s ~190 ns (binary search over ring)
3. Engine & CommitLog Buffered Sequential WAL Mutation (sync_on_write: false) 145,000+ tx/s ~6.8 us
3. Engine & CommitLog Atomic 10-Key TxBatch (TX_BEGIN .. TX_COMMIT, buffered) 62,000+ batches/s (620K keys/s) ~16.1 us per batch
3. Engine & CommitLog Hardware-Synced WAL Commit (sync_on_write: true, NVMe) 9,500 – 18,500 tx/s ~54 – 105 us (NVMe fsync bound)
3. Engine & CommitLog Sparse 24B .idx Binary-Search Historical Seek 32,000+ seeks/s ~31.2 us (O(log N))
4. Cluster Replication Authenticated TCP pull_log_from_peer Catch-Up 115,000+ records/s ~8.7 us per replicated record
5. Durable Execution Memoized 3-Step Workflow Replay (Idempotent Hit) 420,000+ turns/s ~2.38 us (zero side-effect re-run)
6. Reference Workloads PrevailExchange Price-Time FIFO Order Match + WAL 118,000+ orders/s ~8.4 us
6. Reference Workloads PrevailBank Balanced 2-Leg Double-Entry Transfer + WAL 94,000+ transfers/s ~10.6 us
8. SIEM & Streaming RunningStats + HyperLogLog + BoundedRing Observe 14,500,000+ ops/s ~68 ns (O(1) fixed memory)
8. SIEM & Streaming Ephemeral Counterfactual sandbox_replay (8-Cmd Window) 24,000+ replays/s ~41.5 us (zero-copy fork + diff)

2. Durability Flush Mode Trade-Off Matrix

Flush Configuration Crash Survival Guarantee Typical Throughput (Local NVMe) Recommended Workload
Buffered OS Page Cache (sync_on_write = false) Survives vprevail process crashes and restarts (O_APPEND to kernel page cache); abrupt kernel panic or power loss may lose the last ~1–5 seconds of buffered frames (RPO > 0). 110K – 240K ops/s Low-latency caches, session stores, SIEM telemetry windows, AI agent sandboxes, and multi-node clusters where peers pull continuously.
Amortized TxBatch + --sync (sync_on_write = true with batched writes) Survives process kill, kernel panic, and sudden host power loss (RPO = 0 for every committed batch). 80K – 350K keys/s (8K – 25K batches/s) Core banking ledgers (PrevailBank), exchange clearing (PrevailExchange), and high-volume event ingestion.
Single-Key Strict --sync (sync_on_write = true per individual put) Strict per-operation power-loss durability (RPO = 0), bounded physically by storage fsync round-trip latency. 2,200 – 32,000 tx/s (storage-dependent) Low-concurrency compliance registries, root fencing transitions, and human-driven approval workflows.

3. Architectural Comparison vs. External Storage Systems

Capability vprevail Redis / Valkey PostgreSQL TigerBeetle Temporal / Restate
Active State Residence 100% In-RAM 16-Shard CoW MVCC In-RAM Single-Version Dict Disk B-Tree + Shared Buffer Pool In-RAM / Direct-I/O LSM External DB / RocksDB
Point-in-Time Time-Travel Built-in O(1) Offset & HLC Views None Requires pg_partman / Temporal Tables Historical Transfer Immutable Log Event History Replay Only
Multi-Key ACID Transactions Deterministic Single-Writer TxBatch & Closures Lua Scripts (no automatic rollback) MVCC + Lock Manager (2PL / SSI) Fixed Domain Account/Transfer Only Virtual Object Per-Key Only
Built-In Durable Workflows Native DurableRuntime + Sagas + Awakeables in same WAL None External Queue / Polling None Native Orchestrator (separate state DB)
Counterfactual Sandbox Fork Zero-Copy sandbox_replay with Key Diffs None Full DB Clone Required None Replay Debugger Only
External C / Runtime Dependencies Zero (single static-style pure-V binary) libc +jemalloc/TLS Heavy multi-process installation Zero (Zig binary, fixed schema) Multi-service cluster + DB

4. RAM Capacity Planning Formula

Because vprevail is a System Prevalence engine, the active keyspace (StateSpace) must fit comfortably within physical RAM without triggering OS swap thrashing.

Use the following sizing formula for capacity planning:

TEXT
Total_RAM_Bytes =
    (Active_Keys * (Avg_Key_Bytes + Avg_Payload_Bytes + 96_Byte_Record_Overhead))
  * (1.0 + Retained_History_Epochs * Avg_Mutated_Shard_Fraction)
  * 1.35_Headroom_Factor

Worked Sizing Example

  • Active Dataset: 10,000,000 structured records averaging 32 B key + 160 B MsgPack Tuple payload + 96 B map/record metadata = 288 B/key -> 2.88 GB base StateSpace.
  • MVCC Time-Travel Ring: max_version_history = 64 epochs where each {tag} batch mutates 1/16 (6.25%) of one namespace (~400 MB historical CoW delta retention).
  • Recommended Instance RAM: (2.88 GB + 0.40 GB) * 1.35 = ~4.5 GB active footprint -> deploy on an 8 GB RAM instance (leaving ~3.5 GB for OS page cache and non-blocking .snap serialization).

5. Cloud & Bare-Metal Sizing Projections

The following reference matrix matches vprevail's built-in capacity model across popular VPS and public cloud instance families:

Provider / Instance Tier CPU & RAM Specification Storage Backend Wait-Free MVCC Reads/s Buffered WAL Writes/s Synced fsync Commits/s Peer Replication/s Recommended Max Active State & Shards
Hetzner CX22 / CPX11 2 vCPU (Shared x86) / 4 GB RAM Ceph Network NVMe 1.4M - 2.2M ops/s 45K - 75K ops/s 800 - 1,800 tx/s 35K - 60K rec/s 1.8 GB (16 shards)
Hetzner CAX11 / CAX21 2–4 vCPU (Ampere ARM64) / 4–8 GB Ceph Network NVMe 1.8M - 2.8M ops/s 55K - 90K ops/s 900 - 2,000 tx/s 45K - 75K rec/s 4.5 GB (32 shards)
DigitalOcean Premium Droplet 2 vCPU (AMD/Intel) / 4 GB RAM Local NVMe SSD 1.6M - 2.5M ops/s 50K - 85K ops/s 2,200 - 4,500 tx/s 40K - 70K rec/s 2.0 GB (16 shards)
Vultr High Frequency / Linode Ded. 2–4 vCPU (3.2+ GHz) / 8 GB RAM Local Direct NVMe 2.4M - 3.6M ops/s 75K - 120K ops/s 3,500 - 7,500 tx/s 65K - 100K rec/s 4.8 GB (32 shards)
AWS EC2 t4g.medium / m7g.large 2 vCPU (Graviton2/3) / 4–8 GB EBS gp3 (3,000 IOPS) 1.9M - 3.1M ops/s 60K - 105K ops/s 1,200 - 2,800 tx/s 50K - 85K rec/s 4.5 GB (32 shards)
AWS EC2 i4i.xlarge 4 vCPU (Ice Lake) / 32 GB RAM AWS Nitro Local NVMe 3.2M - 4.8M ops/s 110K - 165K ops/s 8,500 - 16,000 tx/s 90K - 140K rec/s 20 GB (64 shards)
GCP c3-standard-4 / c3d-highmem-4 4 vCPU (Genoa / Emerald) / 16–32 GB Titanium Local SSD 3.5M - 5.2M ops/s 120K - 180K ops/s 9,000 - 18,000 tx/s 95K - 150K rec/s 20 GB (64 shards)
Azure Standard_L8s_v3 8 vCPU (EPYC Milan) / 64 GB RAM Direct Local NVMe 3.0M - 4.5M ops/s 100K - 155K ops/s 8,000 - 15,000 tx/s 85K - 135K rec/s 42 GB (128 shards)
Dedicated Bare-Metal (AX42 / Metal) 8–16 Cores (Ryzen / EPYC) / 64–128 GB Gen4 NVMe RAID-1 4.5M - 7.5M ops/s 150K - 240K ops/s 15,000 - 32,000 tx/s 120K - 200K rec/s 85 GB (128 shards)