If you are new to StateVec, do not start from the repository tree.

Start from the runtime model: StateVec runs a business domain as a plugin against a deterministic execution engine. The plugin describes the business state and implements the business rules. The runtime owns execution order, staged mutation, TxResult construction, TxLog, replay, and cluster-facing operation.

30-second version

StateVec is easiest to read as a split:

  • the plugin defines the domain: records, commands, events, keys, indexes, and invariants;
  • the plugin implements deterministic command handlers;
  • the runtime owns ordered execution, staged state change, TxResult, TxLog, replay, and cluster details.

That means business developers spend more time on domain rules and less time rebuilding execution order, durability, replay, repair, and distributed operation around every engine.

What the plugin defines

A StateVec plugin is organized around the domain model:

  • records;
  • commands;
  • events;
  • unique business keys;
  • indexes and prefix lookup paths;
  • invariants checked during execution.

The goal is to let business code talk in business terms. A matching engine should talk about orders, fills, positions, and risk settings. A ledger should talk about accounts, transfers, balances, and settlement states.

What the plugin implements

The plugin implements deterministic command handlers:

command
   |
   v
read canonical state
   |
   v
run domain logic
   |
   v
stage state delta + events
   |
   v
return TxResult

The handler should focus on domain logic:

  • validate the command;
  • read the records and indexes it needs;
  • apply business rules;
  • stage new/update/delete operations;
  • emit domain events;
  • reject invalid transitions.

What the runtime owns

The runtime owns the mechanics that business teams should not rebuild for every engine:

  • ordered execution;
  • generated state accessors;
  • efficient in-memory layout;
  • speculative staged writes;
  • TxResult construction;
  • TxLog durability;
  • replay and audit surfaces;
  • readonly/projection query paths;
  • cluster-facing execution and verification details.

This split is the point of StateVec. Domain developers write the business transition. The runtime makes that transition ordered, durable, replayable, and inspectable.

Record fields and immutability

Records can include immutable fields. These fields are initialized at record creation and remain stable afterward.

Immutable fields are useful for business identity:

  • account id;
  • order id;
  • instrument id;
  • external reference;
  • tenant or ledger id.

Unique business keys and index paths can be built around these fields. The important part is that identity and lookup semantics are part of the schema, not scattered across service code and database helper functions.

Query paths

StateVec is not a general-purpose SQL database.

The intended query path is readonly projection over StateVec-managed state:

  • direct record lookup;
  • unique-key lookup;
  • index lookup;
  • prefix scan;
  • product-specific projection views.

Those projections can be exposed through the protocol that fits the product:

  • HTTP for request/response APIs;
  • gRPC for internal low-latency services;
  • WebSocket for push-style state updates;
  • batch export for downstream analytics.

Where source code fits

The public repository is useful once you know what you are looking for. It contains the runtime implementation, macros, model definitions, and examples.

For first-time readers, use this order:

  1. Read the StateVec overview.
  2. Read this plugin contract.
  3. Read the execution and TxLog blog posts.
  4. Then open the source repository.

That path is intentionally slower than jumping into the tree, but it gives the code a shape before the file names start competing for attention.