stokes
[]

every compiler passed. production still panicked.

statically enforces schema contracts across clickhouse sql, python pipelines, and rust edge proxies. runs in under 38ms in ci with native mcp discovery for cursor and claude code.

$curl -fsSL https://stokes.dev/install.sh | sh
explore cli↓read documentation→

deterministic ci contract gate & native mcp bridge for coding agents

GitHub Actions
Claude Code (MCP)
Cursor (MCP)
GitLab CI/CD
Windsurf (MCP)
IBM Bob (MCP)
ClickHouse
Rustc & Cargo
Python
Cloudflare
GitHub Actions
Claude Code (MCP)
Cursor (MCP)
GitLab CI/CD
Windsurf (MCP)
IBM Bob (MCP)
ClickHouse
Rustc & Cargo
Python
Cloudflare

terminal

cli-first contract engine. native mcp bridge.

run stokes verify in ci for deterministic sub-50ms boundary contract verification. attach stokes mcp to feed verified cross-boundary schemas directly to coding agents.

view cli documentation →view language analyzers →
$stokes mcp --stdio
⎡ · ■ · ⎤stokes-mcp v0.2.0 · protocolVersion: 2024-11-05
⎢ ■ ■ · ⎥connected clients: claude-code · ibm-bob-2.0 · cursor · windsurf
⎣ · · ■ ⎦resources: stokes://contracts · stokes://lockfile · stokes://diagnostics
MCPStdio server initialized with capabilities:
├──tools›stokes_scan, stokes_audit, stokes_verify_patch, stokes_cert
├──resources›stokes://contracts (live ClickHouse ↔ Python ↔ Rust boundary map)
└──prompts›stokes_refactor_contract, stokes_explain_violation
mcp substrate active: listening on stdio (38ms discovery)
stokes://contracts ready

benchmarks

verified in 38ms. 100% deterministic ci verification.

reproducible verification benchmarks across 10,000 property fuzzing test cases. deterministic ast contract analysis completes in under 38ms with zero llm calls.

view verification benchmarks →
ci feedback loop: schema drift detection latencyci testbed · 50k loc workspace

lower is better. time to detect cross-boundary contract drift before code review.

stokes static ast contract check (cross-seam)38 ms
monolingual linters in series (sqlfluff + mypy + cargo)1,840 ms
containerized e2e test suite (docker testcontainers)252,000 ms (4m 12s)
analysis throughput:124,000 ast nodes / sec
resilience & verification profile

deterministic static verification without runtime penalty.

dirichlet edge intake hot path (runtime)
in-place partial selection intake7.66 ns (criterion)
local tree-sitter ast & lockfile pass (ci gate)
cross-boundary contract verification< 38ms
lockfile false-positive rate
comments & code formatting0 false breaks
property fuzzing battery
proptest boundary cases10,000 / 10,000 pass
tested on amd epyc 7763 & apple m3 max

case study · cloudflare nov 18, 2025 outage

out-of-band db grants activate latent cross-boundary defects in git.

the cloudflare incident was triggered by a live database permissions update, but the defect was committed in git: an unqualified reflection query (`system.columns`) coupled to a downstream fixed stack buffer (`[Feature; 200]`). stokes proves this latent capacity violation in the pull request before code reaches production.

view pr conformance →view invariant rules →
T+0mcatalog reflection
replica row duplication

an out-of-band permission grant exposes shard replica tables. the unqualified reflection query in git ingests 280 rows instead of 200 canonical columns.

sqlfluff: pass
T+90msync
KV replication

python pipeline serializes the 280-element payload into KV cache. valid JSON/bytes on the wire, blind to downstream fixed array limits.

mypy: pass
T+91mpanic or 100% drop
TryFromSliceError

the proxy's fixed [Feature; 200] stack buffer ingests 280 entries. localized unwrap causes thread panics; localized Result::Err causes 100% request error drops.

rustc: pass
with stokesseam contract gate
transitive boundary safety

stokes cross-references reflection query scope and serialization sink bounds against downstream buffer capacity. upstream PR CI fails before replication occurs.

blocks invalid payloads upstream

architectural breakdown: panic vs. 100% error rate blackout

why clippy alone does not solve the seam

localized rust error handling (clippy::unwrap_used)

let features: [Feature; 200] = match payload.try_into() {
    Ok(f) => f,
    Err(_) => return Err(PayloadError::CapacityMismatch),
};

satisfies clippy and prevents thread crashes. however, when an uncontracted 280-element payload arrives, every edge worker returns `Err`. instead of panicking, the edge fleet drops 100% of incoming customer traffic with 502 bad gateway responses. the global outage still occurs.

cross-boundary contract verification (stokes verify)

[stokes] FATAL: Boundary breach detected at PR time
ClickHouse reflection query emits 280 column records
Downstream Rust proxy buffer capacity is 200 slots
Upstream PR blocked in CI before deployment.

the defect is not a localized syntax error in the rust service; it is an uncoordinated boundary contract violation. stokes verifies schema reflection scoping and serialization sink bounds in upstream pull requests, ensuring breaking payloads never reach production.

< 38ms
full boundary check
0 Panics
bounds verified
0 LLM Calls
100% deterministic ci
10,000
property fuzzing cases

faq

frequently asked questions

common questions about untyped seams, interface graphs, normalized lockfiles, poly-repo workflows, and ci verification.

view repository on github →
what is stokes & how does it bind multi-language boundaries?+
stokes evaluates static cross-boundary contracts across explicit ClickHouse DDL, Protobuf definitions, and Rust type allocations using tree-sitter AST queries and integer capacity bounds. for dynamic python wire sinks where variable references cannot be resolved statically without whole-program pointer analysis, stokes uses declarative pattern contracts (`stokes.yaml`) and synthesizes certified two-tier bounded deserializers (`TieredBuffer`) to handle runtime variance safely.
why can't single-language linters (sqlfluff, mypy, clippy) catch this? (the context blindness principle)+
local compilers suffer from Context Blindness: sqlfluff cannot see Rust structs, and rustc cannot see ClickHouse migrations. consider a valid DDL migration adding 2 fraud detection columns: sqlfluff passes (100% valid DDL), mypy passes (valid dictionary), and rustc passes (valid `[Feature; 200]`). each file passes in isolation, but the system panics because N_max (202) > M_downstream (200). the defect exists solely in the cross-compiler cardinality inequality, which only Stokes evaluates.
why not just use protobuf, grpc, or an idl?+
traditional IDLs are prescriptive: they generate code stubs that force teams to rewrite existing storage layers, yet cannot govern analytical ClickHouse DDL, dynamic KV meshes, or Python dataframes. `stokes.yaml` is not an IDL; it is a descriptive, zero-code-generation linter manifest (analogous to `.eslintrc.json`) for teams with custom internal wrappers. for standard wire sinks (`kv.put`, `cache.set`, SQL migrations, and Rust arrays), Stokes operates zero-config out of the box.
how does stokes prevent poly-repo lockstep deadlocks?+
stokes enforces the standard Consumer Expands First (Tolerant Reader) deployment lifecycle. the downstream consumer expands buffer capacity first (e.g. from 200 to 512), which merges immediately because larger buffers are backward-compatible with 200-element payloads. upstream producers expand emission second. running `stokes verify --consumer=... --producer=...` verifies that consumer capacity exceeds producer emission, eliminating circular deadlocks and manual JSON drift.
if control planes have Last-Known-Good (LKG) rollback, why do we need stokes in CI?+
LKG rollback is an emergency airbag; Stokes is the steering wheel. when an uncontracted schema expansion reaches production, control plane LKG rollback preserves edge stability, but at a severe operational cost: the catalog sync pipeline fails, the new release is aborted in production, feature rollouts stall, and on-call engineers are paged to initiate emergency cross-repo rollbacks. you do not deploy broken migrations just because PostgreSQL has transaction rollbacks, and you do not deploy broken containers just because Kubernetes restarts failing pods. Stokes shifts failure left into the Pull Request, blocking broken code before the image is built and before production rollbacks are ever triggered.

ready to eliminate cross-boundary panics?

install stokes to run autonomous cross-compiler verification across ClickHouse, Python, and Rust in your pre-commit hooks and ci pipelines.

read documentation→explore cli↓