sscoble/speckl
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

Merge branch 'feature/z3-backend' (Z3 backend + KRaft spec)

Browse source
This commit is contained in:
Scott Scoble 2026-05-09 22:34:40 -07:00
parent 6c6daaf90f
commit c5ca757e80
12 changed files with 81 additions and 956 deletions
Download patch file Download diff file Expand all files Collapse all files

32
README.md
View file

@ -2,7 +2,7 @@
**A judgement transport utility for AI-generated specifications.** Fulfills NIST SA-11 (human-in-the-loop for automated outputs).
Speckl is a specification language (SpeckDL) with a compiler that produces runnable software — WebAssembly, TypeScript, and provenance artifacts (PROV-O, CycloneDX, SPDX) — from a single source of truth. Write what your system should do. Prove it. Ship it.
Speckl is a specification language (SpeckDL) with a compiler that produces runnable software — TypeScript and provenance artifacts (PROV-O, CycloneDX, SPDX) — from a single source of truth. Write what your system should do. Prove it. Ship it.
## The Core Insight
@ -17,8 +17,7 @@ AI generates code at machine speed. Humans own specifications. **SpeckDL is the
Speckl is a **working compiler** that turns formal specifications into multiple target representations:
```
.speckdl spec ──→ Wasm (WebAssembly) ← runnable, verified state machines
├── TypeScript ← typed, importable classes
.speckdl spec ──→ TypeScript ← typed, importable classes
├── PROV-O (RDF) ← W3C provenance standard
├── CycloneDX SBOM ← OWASP software bill of materials
└── SPDX SBOM ← Linux Foundation SBOM standard
@ -46,7 +45,7 @@ spec ToggleSwitch {
}
```
This compiles to a runnable WebAssembly module with verified state transitions + guards, and to a type-safe TypeScript class. Both from the same spec.
This compiles to a runnable TypeScript class with verified state transitions + guards.
### Provenance Embedded at Compile Time
@ -58,12 +57,12 @@ The compiler has been validated against:
| Example | Source | Status |
|---------|--------|--------|
| **ToggleSwitch** | SpeckDL tutorial | ✅ All 5 artifacts |
| **AccountLedger** | Banking ledger with debit/credit | ✅ All 5 artifacts |
| **TwoPhaseCommit** | TLA+ port | ✅ All 5 artifacts |
| **Paxos** | TLA+ port | ✅ All 5 artifacts |
| **Raft** | TLA+ port | ✅ All 5 artifacts |
| **TigerBeetleLedger** | Naive TigerBeetle core | ✅ All 5 artifacts (3 TS type errors in progress) |
| **ToggleSwitch** | SpeckDL tutorial | ✅ All artifacts |
| **AccountLedger** | Banking ledger with debit/credit | ✅ All artifacts |
| **TwoPhaseCommit** | TLA+ port | ✅ All artifacts |
| **Paxos** | TLA+ port | ✅ All artifacts |
| **Raft** | TLA+ port | ✅ All artifacts |
| **TigerBeetleLedger** | Naive TigerBeetle core | ✅ All artifacts (3 TS type errors in progress) |
## Getting Started
@ -72,10 +71,10 @@ git clone https://os.scoble.me/forgejo/sscoble/speckl
cd speckl/compiler
npm install
# Compile an example to all 5 targets
# Compile an example
node dist/index.js ../examples/ToggleSwitch.speck -o out/switch
ls out/switch/
# ToggleSwitch.wat ToggleSwitch.ts ToggleSwitch.prov-o.jsonld
# ToggleSwitch.ts ToggleSwitch.prov-o.jsonld
# ToggleSwitch.cyclonedx.json ToggleSwitch.spdx.json
```
@ -99,11 +98,10 @@ ls out/switch/
## Validation Status
- **Compiler:** 41/41 tests passing (WASM + TypeScript codegen)
- **WASM E2E:** wabt assemble + instantiate + run verified
- **TypeScript:** Dual-target compilation — same spec produces both WASM and TS
- **TLA+ Trilogy:** TwoPhaseCommit, Paxos, Raft all compile (WAT validates through wabt)
- **Compiler Self-Spec:** `speckl-compile.speckdl` defines the Speckl compiler in SpeckDL — generates all 5 artifacts (known TypeScript errors tracked in engineering#9)
- **Compiler:** 41/41 tests passing (TypeScript codegen)
- **TypeScript:** Type-safe compilation from specs
- **TLA+ Trilogy:** TwoPhaseCommit, Paxos, Raft all compile
- **Compiler Self-Spec:** `speckl-compile.speckdl` defines the Speckl compiler in SpeckDL — generates all artifacts (known TypeScript errors tracked in engineering#9)
## Known Issues