Verification for distributed systems

Don’t assume.
Prove it.

Your suite is green. That is a fact about the tests someone wrote — not about the system you are shipping.

SODL reads your service’s own contract, derives what is actually verifiable from it, runs your scenarios against the live system, and writes down what it proved. Fresh, every run. Nothing authored, nothing stored, nothing test-related in your contract.

Get started — one minute How it works

gRPC / protobuf · OpenAPI 3.0 · Swagger 2.0 · free anonymous install, no account

scenarios/create-and-approve.sodl

scenario CreateAndApprove {
  customer = CreateCustomer( name: "Ann" ) as admin
  created  = CreateOrder( customer_id: customer.customer_id ) as customer
  order    = GetOrder( order_id: created.order_id )
  waitUntil order reached APPROVED
}

That is the whole thing. Every name in it — the operations, the fields, APPROVED — is checked against your contract before the scenario is allowed to run.

The gap

Three questions to put to your current suite

Not rhetorical. Each has an answer, and the answer is the product.

Which operations does no test touch?

A test engine cannot answer this: it knows the tests you wrote and nothing else. Because SODL derives the whole surface from your contract, it has a denominator — and can name the operations nothing exercises.

Can it fail a deploy for a field that nothing tests?

Removed fields, removed operations and removed enum states break consumers whether or not you happened to cover them. SODL compares contracts, not just tests, so an uncovered breaking change still fails the gate.

Can you prove what verified, against what, last Tuesday?

Every run writes an immutable record: what ran, against which contracts, in which environment, when, by which version. A system of record — not a report that scrolls off the terminal.

If the answer to all three is no, that gap is not a feature anyone can add to the tool you have. It is a different architecture — and the difference starts one step earlier than testing.

The one idea

It reads your contract, not your test file

Most tools take your word for it. You write the request, you write the expected response, and the tool faithfully executes your description of a system that may no longer exist.

You own this

Your contract

.proto, an OpenAPI document, or a live gRPC reflection endpoint. Untouched — nothing test-related goes in it.

discover

Derived

Verification surface

Operations, entities, which field is identity, how entities correlate, enum-backed lifecycles, every field’s shape.

interpret

Checked

Your scenario, compiled

Type-checked against the derived surface. An invalid scenario is rejected before it runs, not twenty minutes into a red build.

execute

Proved

Run & evidence

Executed against the live system, including waiting for asynchronous state to settle. Then written down, immutably.

Re-derived on every single run. There is no stored model to go stale.

It waits, instead of sleeping

waitUntil order reached APPROVED watches the real system until the condition is true — or tells you exactly where it stalled. No sleep(5), no flake budget.

It asks, instead of guessing

If two operations could be what you meant, SODL stops and makes you say which one — once, on purpose. Ambiguity resolved silently is a bug with a delay fuse.

It resolves credentials late

Principals are resolved at the moment they are needed, not read from a token going quietly stale in a config file.

What you get

Five capabilities.
Four are impossible without the first.

Running the test is one output of five. Coverage, drift and evidence all rest on derivation — which is why bolting “derive and type-check” onto an authoring tool produces a linter, not this.

See each one with its real output →

1

Derive

The verifiable surface is computed from the wire contract, never written by hand. A scenario that no longer matches the API fails to compile.

2

Prove

Run it against the live system. PASS or FAIL. The one output a test engine also produces.

3

Coverage

Because SODL knows the whole surface, it can name what no scenario touches. A test engine has no denominator.

4

Drift

A breaking contract change fails the gate even when no scenario covers it. A test engine only fails on paths you happened to cover.

5

Evidence

Every run writes an immutable, contract-anchored record. A system of record, not an ephemeral report.

The artifact

A page you can hand to someone who was not there

sodl report renders the latest run record as one self-contained page: the verdict, the counts, the whole suite tree, the provenance header — and a section stating what the record does not prove.

Structure of the report page

Headline — the counts, as a sentence

passed failed skipped not served

Provenance project · environment · contracts digest · started · sodl version

Findings one card per row that did not pass — position, then the message verbatim

Suite ledger the folder tree, every scenario, its state and duration

Coverage

operations exercised, of the derived total

What this record does not prove — stated on the page, not in a footnote.

The structure, named. Proportions are illustrative — no run is being reported here.

The page follows one law: it may point, never explain. Every string on it is evidence — a count, a name, a file:line:col, a failure message verbatim, a timestamp. It never editorialises, never speculates about causes, and never summarises a failure in its own words.

Where it fits, and where it does not

SODL earns its place where a workflow spans services or takes time to settle. Where that is not the shape of your problem, an ordinary test framework is the right answer and SODL will not pretend otherwise.

Read the boundaries in full →

Good fit

Workflows crossing several services
Asynchronous state that settles later
Contracts that change under you
Release gates that must be defensible

Not this

UI testing
Load and performance testing
Unit tests
Systems with no published contract

One minute

Try it on your own repository

No account, no token, no sign-up. The installer detects your platform, verifies the download against SHA256SUMS, and installs into a user directory — no admin rights.

macOS / Linux

$ curl -fsSL https://github.com/rajsinghsisodia/sodl-releases/releases/latest/download/install.sh | sh

Windows — PowerShell

> irm https://github.com/rajsinghsisodia/sodl-releases/releases/latest/download/install.ps1 | iex

then, in your repo

$ sodl init -yes      # reads your contracts, writes sodl.yaml
$ sodl analyze       # what SODL understood — and what it could not
$ sodl run           # prove it against your running service
$ sodl report -open  # the run, as a page you can share

Four commands, and the first three need no running service at all.

The one-minute walkthrough What it cannot do

Don’t assume.Prove it.

Three questions to put to your current suite

It reads your contract, not your test file

It waits, instead of sleeping

It asks, instead of guessing

It resolves credentials late

Five capabilities.Four are impossible without the first.

Derive

Prove

Coverage

Drift

Evidence

A page you can hand to someone who was not there

Where it fits, and where it does not

Good fit

Not this

Try it on your own repository

Don’t assume.
Prove it.

Five capabilities.
Four are impossible without the first.