speckl/README.md

# Speckl

**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.

## The Core Insight

AI generates code at machine speed. Humans own specifications. **SpeckDL is the shared space where both can work.**

- **Human-judgeable** — SpeckDL is declarative enough that a person can inspect a spec and say "yes, this captures my intent." The compiled output is opaque; the spec is not.
- **AI-writable** — SpeckDL's constrained grammar and declarative semantics are tractable for LLMs to produce and reason about. Agents draft. Humans review. Both operate on the same semantic layer.
- **Compiled, not generated** — The SpeckDL compiler is deterministic. No LLMs in the compilation path. Same spec, same output — always.

## What Speckl Does Now

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
              ├── PROV-O (RDF)           ← W3C provenance standard
              ├── CycloneDX SBOM         ← OWASP software bill of materials
              └── SPDX SBOM              ← Linux Foundation SBOM standard
```

### State Machine Compilation (inspired by TLA+)

```speckdl
spec ToggleSwitch {
  state: Status = Off
  enum Status = On | Off

  init: {
    Status = Off
  }

  action FlipSwitch {
    require: true
    if Status == On {
      Status = Off
    } else {
      Status = On
    }
  }
}
```

This compiles to a runnable WebAssembly module with verified state transitions + guards, and to a type-safe TypeScript class. Both from the same spec.

### Provenance Embedded at Compile Time

Every compilation embeds a complete provenance record — PROV-O RDF traces the spec → code derivation, CycloneDX and SPDX SBOMs capture the software supply chain. When an auditor asks "where did this behavior come from?", you query the graph, not Jira.

## Real-World Examples

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) |

## Getting Started

```bash
git clone https://os.scoble.me/forgejo/sscoble/speckl
cd speckl/compiler
npm install

# Compile an example to all 5 targets
node dist/index.js ../examples/ToggleSwitch.speck -o out/switch
ls out/switch/
# ToggleSwitch.wat  ToggleSwitch.ts  ToggleSwitch.prov-o.jsonld
# ToggleSwitch.cyclonedx.json  ToggleSwitch.spdx.json
```

### Key Documents

- **[Whitepaper v2](docs/whitepaper-v2.md)** — Complete: 8 sections, ~19,000 words. Covers the spec-code gap, SpeckDL language, compiler architecture, embedded provenance, consensus protocols, compliance applications, related work, and roadmap.
- **[Speckl by Example](docs/speckl-by-example.md)** — Guided tutorial from ToggleSwitch through Raft, with TLA+ comparison table.
- **[Distribution Strategy](docs/distribution-strategy.md)** — Prioritized roadmap: Show HN → arXiv → blog → consulting pipeline. Conference landscape for 2026-2027.
- **[Strategy Ladder](docs/strategy.md)** — Open standard → Consulting → Developer Tool/SaaS → Compliance API.
- **[SpeckDL Spec](speckdl/SPEC.md)** — Language definition v0.2.
- **[State Machine Extension](speckdl/STATE-MACHINE-SPEC.md)** — `state`/`init`/`action` keywords, Set/Map/List types.

## Strategy Ladder

| Phase | Focus | Status |
|-------|-------|--------|
| **A — Open Standard** | SpeckDL language, compiler, whitepaper, examples | ✅ **Complete** (compiler working, whitepaper done) |
| **B — Consulting** | Hands-on engagements with regulated-industry teams | 📋 One-pager drafted, awaiting review |
| **C — Developer Tool/SaaS** | Self-serve spec validation, provenance browser | 🔮 Future |
| **D — Compliance API** | Enterprise audit reports, traceability matrices | 🔮 Future |

## 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)

## Known Issues

The `rewriteExpr` function in the TypeScript generator applies spurious `this.state.` prefixes to function parameters in guard expressions. Tracked in [marcus/engineering#9](https://os.scoble.me/forgejo/marcus/engineering/issues/9). Parser also drops `precondition:`/`postcondition:` blocks on some action bodies.

## Contributing

Speckl is open source under the [MIT license](LICENSE). Contributions welcome:

- **Language design** — refine SpeckDL syntax and semantics
- **Compiler development** — TypeScript/Node.js, help fix open issues
- **Formal methods** — verify the compilation pipeline, add TLA+ examples
- **Compliance expertise** — validate regulatory models (NIST, IEC 62304, DO-178C)
- **Documentation** — tutorials, guides, case studies

Open an issue or submit a pull request.

## License

MIT © Scott Scoble / Greybeard Holdings, LLC

## Mirrors

- **Primary:** https://os.scoble.me/forgejo/sscoble/speckl
- **Mirror:** https://codeberg.org/sscoble/speckl