conformance

verifiable lockfile. cryptographic trust.

bridge machine-readable schema lockfiles with human-readable audit attestations. immutable sha-256 digests for cross-team compliance.

run verification gate→explore outage case study→

stokes.lock (machine) / CONFORMANCE.md (audit)

digest verified

boundary conformance certificatesha-256: e3b0c44298fc1c14...855

verification battery status

✓clickhouse schema: 200 canonical features verified

✓transitive qualification: WHERE database = currentDatabase() verified

✓rust proxy: [FeatureDescriptor; 200] stack buffer verified

✓dual-zone partitioning: zone 0 (128 slots) + zone 1 (72 slots)

✓hot-path latency: 7.66 ns <= 10.0 ns SLA

✓heap allocations: 0 b <= 0 b budget

✓property fuzz tests: 10,000 / 10,000 passed in 1.42s

attestation manifest

target workspace:dirichlet-proxy

engine:stokes verification engine

verification time:1.42 seconds

ci enforcement:strict pre-merge gate

author:yvliet

# machine-readable lockfile signature block:

"signature": "stokes-sig-v1:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

tamper-proof boundaries

how cryptographic lockfiles stop drift before deployment.

in modern distributed systems, analytical schemas and microservice buffers live in separate repositories. stokes binds them cryptographically into a two-tier contract system: a machine-authoritative lockfile (stokes.lock) for ci enforcement, and a human-readable audit certificate (CONFORMANCE.md) for pr reviews.

normalized semantic ast hashing

every column definition, analytical data type, and array buffer size is extracted from the AST and hashed into a canonical root digest. comments, docstrings, and code formatting are discarded to prevent false breaks.

machine-authoritative stokes.lock

committed directly into git alongside code. evaluated by stokes verify --strict in ci/cd pipelines to block prs on uncontracted drift.

human-readable CONFORMANCE.md

self-documenting markdown certificate summarizing capacity margins, benchmark timings (7.66 ns), and fuzz test coverage for pr reviewers.

deterministic pr gate

any pull request that adds or modifies analytical schema without updating the corresponding proxy buffers is automatically rejected.

stokes.lock (canonical json representation)

{
  "$schema": "https://stokes.dev/schema/v1.json",
  "version": "1.0.0",
  "workspace": "dirichlet-l7-proxy",
  "root_digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "verification_mode": "normalized_semantic_ast",
  "invariants": {
    "max_features": 200,
    "downstream_capacity": 200,
    "cardinality_risk_ratio": 1.40,
    "zero_panics_verified": true
  },
  "targets": [
    {
      "id": "clickhouse-schema",
      "path": "migrations/001_bot_signals.sql",
      "digest": "sha256:4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a"
    },
    {
      "id": "rust-proxy-buffer",
      "path": "crates/dirichlet-proxy/src/engine/feature_ingest.rs",
      "digest": "sha256:ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d"
    }
  ]
}

lockfile validation speed:< 15 ms

digest algorithm:standard sha-256

[sha-256 digest]

tamper-proof invariants

cryptographic schema hashing guarantees that any unreviewed field change or buffer size adjustment immediately invalidates the lockfile.

[ci pre-merge gate]

automated defense

runs as an automated, non-bypassable github actions check on every pull request, ensuring production deployments never inherit drift.

[audit receipt]

audit summary

produces a self-contained markdown audit manifest (CONFORMANCE.md) detailing schema hashes, benchmark numbers, and test results for pull request review.

conformance faq

lockfile & audit receipt questions

details on sha-256 digests, tamper resistance, and ci/cd compliance policies.

what is the difference between stokes.lock and CONFORMANCE.md?+

stokes.lock is a machine-authoritative JSON lockfile containing SHA-256 hashes of canonical semantic AST signatures, ingested by `stokes verify --strict` in CI. CONFORMANCE.md is a human-readable markdown audit summary generated for PR reviewers, compliance teams, and post-incident verification.

how does normalized semantic AST hashing prevent false positives?+

stokes parses the syntax tree of your code and hashes only the contract interface: table columns, types, nullability, fixed buffer sizes, and query predicates. comments, whitespace, variable formatting, and internal helper functions are ignored, so running black or rustfmt never invalidates stokes.lock.

should stokes.lock be committed to version control?+

yes. committing stokes.lock guarantees that contract invariants are tracked across git history, preventing silent schema drift between different feature branches and staging environments.

what happens when a pull request introduces an uncontracted schema change?+

stokes verify runs as a required GitHub Actions status check. if an upstream migration adds columns without an authorized lockfile update and buffer re-certification, the check exits with code 1 and blocks merging.

how does stokes.lock coordinate contracts across separate git repositories (poly-repo)?+

in poly-repo setups, the upstream repo (e.g. clickhouse ddl) exports its certified schema digest as a release artifact or registry record. the downstream proxy repo pins that digest inside its local stokes.lock (upstream_schema_digest: sha256:...). during upstream pull request CI, stokes verify evaluates whether proposed DDL changes alter the pinned consumer digest. if an upstream PR expands or alters consumed fields, the upstream check fails before merge, requiring explicit downstream buffer re-certification.

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↓