Speckl

What Speckl Does

Speckl is a compiler for state machine specifications. You write what your system should do in SpeckDL — a typed specification language with states, actions, invariants, and guard conditions. The compiler produces five auditable artifacts from a single spec:

No LLMs in the compiler. Same spec, same output, every time. Every compilation embeds provenance — PROV-O traces, CycloneDX and SPDX SBOMs — so auditors can trace any generated code back to its specification.

• Provenance is embedded by construction — not bolted on after the fact
• 41 tests passing, < 2 seconds to run the full suite
• 14 example specks: ToggleSwitch → TwoPhaseCommit → Kafka KRaft → Paxos → Raft
• Dual-target: TypeScript state machine classes + Z3 SMT verification from the same spec
• Zero external services — everything runs locally

SpeckDL by Example

SpeckDL is a typed specification language for state machines. Define your states, actions, preconditions, and mutations — the compiler handles the rest.

// A simple toggle switch — compiles to TypeScript + 3 provenance artifacts
spec ToggleSwitch {
  type Status = enum { On, Off }

  state {
    status: Status = Status.Off
  }

  init Start() {
    set status = Status.On
  }

  action Flip() {
    require status == Status.On
    set status = Status.Off
    emit "TurnedOff"
  }

  action FlipBack() {
    require status == Status.Off
    set status = Status.On
    emit "TurnedOn"
  }

  invariant "At most one pending action" {
    !(status == Status.Flip && !(status == Status.FlipBack))
  }
}

Type system: Int · Float · Bool · String · Enum · Struct · List<T> · Set<T> · Map<K,V>  |  Keywords: spec · type · state · init · action · require · set · emit · invariant

Real Examples

Status & Roadmap

• TypeScript codegen: Complete — state machine classes with full type coverage
• Z3 verification backend: Live — --target=z3 emits SMT-LIB2 that Z3 accepts
• OAuth 2.0 spec: Exists — examples/OAuth2AuthorizationCode.speckdl
• Rust codegen: In progress (M2.1)
• WASM via wasm-pack: Pending Rust codegen completion

The WAT/WASM generator was removed in favor of a proper IR → Rust → wasm-pack pipeline. No hand-rolled WASM text format; no magic.

Try It

# Clone the repo
git clone https://github.com/wscoble/speckl.git
cd speckl/compiler

# Build and run tests (41 tests, ~2s)
npm install
npm test

# Compile a spec to TypeScript + provenance artifacts
node dist/index.js ../examples/TwoPhaseCommit.speckdl -o out/twophase

# Compile to Z3 SMT-LIB2 for verification
node dist/index.js ../examples/KafkaKRaft.speckdl --target=z3 -o out/kraft

# Check TypeScript validity
npx tsc --noEmit -p out/twophase

Shipping Code an Agent Wrote?

Speckl makes the spec checkable. The release still needs a gate. I keep the checks I run before code goes to production on one page, for code written by people or by coding agents.