stokes

cli

terminal native. deterministic workflow.

from single-command workspace audit to cryptographic certificate generation, deterministic platform tooling built for your terminal.

explore command suite↓view benchmarks→
stokes audit --diff (interactive terminal session)
exit: 0 (remediated)
$ stokes audit --diff

[1/4] traversing workspace ast boundaries...

✓ migrations/001_bot_signals.sql (200 canonical signals indexed)

✓ services/feature-pipeline/extractor.py (dynamic dictionary bounds traced)

▲ crates/dirichlet-proxy/src/engine/feature_ingest.rs (fatal slice unwrap on overflow)

error: boundary contract violation: cardinality risk ratio = 1.40

clickhouse reflection matches: 280 features (200 canonical + 80 shard replicas)

rust l7 proxy allocates: [Feature; 200] (fixed stack array)

risk: TryFromSliceError panic on element index 201 crashes l7 proxy worker threads

stokes remediation proposal (automated patch):

architecture: defensive bounds & catalog qualification

clickhouse: scoped reflection query with AND database = currentDatabase()

rust proxy: explicit Result<[Feature; 200], PayloadError> bounds guard

heap memory overhead: 0 bytes (fits in 25 cache lines, 100% l1d cache resident)

? apply zero-allocation patch to crates/dirichlet-proxy? [y/n]:y

✓ patch applied to crates/dirichlet-proxy/src/engine/feature_ingest.rs

✓ validated against 10,000 randomized property fuzz test cases in 1.42s

✓ conformance lockfile written: stokes.lock (sha256: e3b0c44298fc1c14...855)

workspace certified safe for production deployment.

continuous enforcement

integrate stokes into pre-commit and github actions.

stokes is designed to be frictionless for local developers and non-negotiable in automated ci pipelines. catch contract drift on the engineer's machine before code is committed, and enforce strict boundary verification on every pull request.

01

local git pre-commit hook

stokes stage-check runs in under 50 milliseconds against staged files, alerting developers instantly before git commits.

02

interactive terminal remediation

stokes audit --diff reveals cross-compiler drift and suggests zero-allocation patches that can be reviewed and accepted in place.

03

non-bypassable ci gate

in github actions or gitlab ci, stokes verify --strict runs as a mandatory check, blocking prs that introduce uncontracted fields.

04

cryptographic audit certificate

stokes cert emits human-readable CONFORMANCE.md alongside machine-verifiable stokes.lock with sha-256 digests.

.github/workflows/stokes.yml
name: boundary conformance gate
on: [pull_request, push]

jobs:
  stokes-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: install stokes cli
        run: cargo install stokes-cli --locked
        
      - name: verify cross-boundary invariants
        run: stokes verify --lockfile=stokes.lock --strict
        
      - name: validate micro-benchmark budget
        run: stokes bench --max-p99-ns=10.0 --max-heap-bytes=0
        
      - name: generate audit certificate
        run: stokes cert --output=CONFORMANCE.md
average ci run duration:1.8s (cached build)
bypass prevention:mandatory status check

command reference

complete stokes cli command matrix.

$ stokes scaninspection

statically traverses ClickHouse SQL migrations, Python ETL pipelines, and Rust proxy crates. emits unified ast summary of all canonical features.

flags: --strict, --json, --contracts
$ stokes stage-checkpre-commit

lightweight pre-commit gate that scans git staged files in under 50 milliseconds. blocks commit if boundary invariants are violated.

flags: --hook, --quiet
$ stokes auditdiagnostic

runs parallel ast analyzers to identify cross-boundary schema drift and generate in-place degradation diffs.

flags: --diff, --export-patch, --strict
$ stokes benchbenchmark

executes criterion micro-benchmarks and heap allocation profilers. validates that hot-path execution stays within the 10.0 ns and 0 b limits.

flags: --max-p99-ns=10, --max-heap=0
$ stokes verifyci gate

deterministic validation against stokes.lock. returns non-zero exit code if workspace drift occurs without lockfile update.

flags: --lockfile=stokes.lock, --strict
$ stokes codegensynthesis

synthesizes certified zero-heap buffers (TieredBuffer) directly into consumer AST boundaries, safely handling uncontracted runtime variance.

flags: --consumer, --write, --strict
$ stokes certattestation

computes cryptographic sha-256 schema digests and writes signed CONFORMANCE.md audit certificate for compliance and review.

flags: --output=CONFORMANCE.md, --sha256

cli faq

cli & terminal workflow questions

details on git hooks, flags, ci gating, and external agent integrations.

how fast does stokes stage-check run in pre-commit hooks?+
stokes stage-check completes in under 50 milliseconds. it parses only git-staged file buffers using Tree-sitter AST queries, allowing engineers to verify cross-boundary invariants locally before committing without workflow lag.
how does stokes audit synthesize remediation diffs?+
stokes audit runs 5 language-specific analysis workers (sql, python, rust, protobuf, test verification) over an in-process event bus. when a cardinality mismatch is detected, it generates an actionable remediation diff scoping upstream sql reflection queries and adding defensive bounds validation (Result<_, PayloadError>) in downstream services.
what happens when stokes verify runs in CI with --strict?+
in CI environments, stokes verify re-computes normalized semantic AST digests for every schema and buffer file listed in stokes.lock. if any column was added, query predicate modified, or buffer capacity altered without lockfile updates, it exits with code 1 and blocks the pull request, while safely ignoring comments and formatting.
how does stokes mcp integrate with Cursor and Windsurf?+
stokes mcp runs a native Model Context Protocol server over stdio. it exposes cross-boundary diagnostics (LINT-001 through LINT-005) directly to IDE AI agents, enabling real-time contract linting while editing code.
how does stokes codegen synthesize safe runtime buffers?+
stokes codegen inspects downstream consumer ASTs and synthesizes certified two-tier bounded deserializers (TieredBuffer). payloads up to N evaluate inline on the stack with zero allocations (< 1 ns), while payloads up to MAX use bounded spillover memory, preventing panics and 502 blackouts.

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↓