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.
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.
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.
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.
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
Consolidated single-volume compilation of all seven End-User, Administrator, and Operations guides.
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):
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:
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"
}'
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
}'
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
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.
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/.
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
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.
Tab 1: Sign In
Enter your Principal Identifier (for example usr:alice or admin:root) and Display Name.
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).
Enter your Tenant Namespace (for example tenant:quant) and, when the gateway is started with --auth-token, provide the Cluster Bearer Token.
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.
Writing Permanent & Ephemeral Records
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.
Set TTL Nanoseconds (0 for permanent persistence, or a positive nanosecond duration such as 3600000000000 for 1 hour).
Enter valid JSON in JSON Value Payload and click Put Record.
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
Note the Updated Offset column on earlier versions of your keys.
Enter any historical CommitLog offset into Time-Travel Offset (0 = latest) (for example 8) and click Query / Time-Travel Scan.
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.
Switch to My Workflows & Awakeables to launch stateful Virtual Objects and Restate-style durable workflows:
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).
Provide Input JSON and click Invoke Durable Workflow.
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:
Optionally enter a Namespace Filter (such as studio_bank_ledger or leave empty for all namespaces) and a Key Prefix Filter (such as wire-).
Click Create Subscription to allocate a bounded non-blocking subscriber ring (max_queue = 256).
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.
Click Unsubscribe when finished to release the subscriber slot cleanly.
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).
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:
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).
64-Register HyperLogLog: Estimates distinct cardinality (such as unique source IPs or trading accounts) in 64 bytes of state.
BoundedRing Circular Buffers: Retains the most recent N observations per entity with deterministic oldest-item eviction.
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
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).
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)
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).
Switch to CommitLog, Snapshots & Inspector to manage disk lifecycle safely:
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.
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.
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.
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.
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:
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).
Always Configure Non-Empty Secrets: Pass a high-entropy 32+ byte --auth-token (256 bits of CSPRNG entropy) in production.
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)
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.
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:
Do not overwrite the affected directory; archive it for hardware diagnostics.
Provision a clean --data-dir on healthy NVMe media.
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:
On the authoritative target node, verify that __system_fencing holds the higher monotonic fencing term via /ui/admin (admin-cluster -> Check Fencing Term).
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:
Confirm all async replicas have pulled past the target offset.
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"}).
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
}'
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
}'
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
}'
PulseLedger demonstrates hybrid multi-model storage during high-concurrency retail flash sales by combining three storage representations inside a single atomic transaction:
wallets Namespace (Integer Values): Customer spending balances in minor currency units (cents).
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.
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.
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
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
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.
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.
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).
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:
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.
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.
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.
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.
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
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):
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:
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"
}'
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
}'
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
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.
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/.
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.
Tab 1: Sign In
Enter your Principal Identifier (for example usr:alice or admin:root) and Display Name.
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).
Enter your Tenant Namespace (for example tenant:quant) and, when the gateway is started with --auth-token, provide the Cluster Bearer Token.
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.
Writing Permanent & Ephemeral Records
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.
Set TTL Nanoseconds (0 for permanent persistence, or a positive nanosecond duration such as 3600000000000 for 1 hour).
Enter valid JSON in JSON Value Payload and click Put Record.
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
Note the Updated Offset column on earlier versions of your keys.
Enter any historical CommitLog offset into Time-Travel Offset (0 = latest) (for example 8) and click Query / Time-Travel Scan.
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.
Switch to My Workflows & Awakeables to launch stateful Virtual Objects and Restate-style durable workflows:
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).
Provide Input JSON and click Invoke Durable Workflow.
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:
Optionally enter a Namespace Filter (such as studio_bank_ledger or leave empty for all namespaces) and a Key Prefix Filter (such as wire-).
Click Create Subscription to allocate a bounded non-blocking subscriber ring (max_queue = 256).
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.
Click Unsubscribe when finished to release the subscriber slot cleanly.
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:
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).
64-Register HyperLogLog: Estimates distinct cardinality (such as unique source IPs or trading accounts) in 64 bytes of state.
BoundedRing Circular Buffers: Retains the most recent N observations per entity with deterministic oldest-item eviction.
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
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).
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)
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).
Switch to CommitLog, Snapshots & Inspector to manage disk lifecycle safely:
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.
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.
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.
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.
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:
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).
Always Configure Non-Empty Secrets: Pass a high-entropy 32+ byte --auth-token (256 bits of CSPRNG entropy) in production.
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)
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.
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:
Do not overwrite the affected directory; archive it for hardware diagnostics.
Provision a clean --data-dir on healthy NVMe media.
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:
On the authoritative target node, verify that __system_fencing holds the higher monotonic fencing term via /ui/admin (admin-cluster -> Check Fencing Term).
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:
Confirm all async replicas have pulled past the target offset.
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"}).
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
}'
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
}'
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
}'
PulseLedger demonstrates hybrid multi-model storage during high-concurrency retail flash sales by combining three storage representations inside a single atomic transaction:
wallets Namespace (Integer Values): Customer spending balances in minor currency units (cents).
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.
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.
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
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.
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.
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).
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: