diff --git a/docs/PROVE-KAFKA-PLAN.md b/docs/PROVE-KAFKA-PLAN.md index 00bb9b7..80a25ae 100644 --- a/docs/PROVE-KAFKA-PLAN.md +++ b/docs/PROVE-KAFKA-PLAN.md @@ -20,37 +20,39 @@ Dependencies only. No wall-time estimates. Each milestone lists what must be tru The compiler must be able to accept real specs and produce verified artifacts. Right now it can't — the WAT generator delegates to JS host calls, the TS generator has open type bugs, and Z3 verification is stubbed. -### M0.1 — TypeScript Reference Backend (Clean Build) +### M0.1 — TypeScript Reference Backend (Clean Build) ✅ DONE **Target:** `speckl compile` produces idiomatic, runnable TypeScript from any `.speck` file. All 12 examples compile and pass generated tests. **Dependencies:** None (starts now) -**Deliverables:** -- Fix engineering#9 (spurious `this.state` prefix in guards) -- Fix engineering#11 (record type emission for TS) -- Fix engineering#12 (5 expression pattern translations to JS) -- All 12 example specs compile to TypeScript without errors -- Generated TypeScript passes basic smoke tests (state transitions, guard checks, event emission) -- Delete WAT generator (superseded by IR→Rust→WASM path in M1.2) +**Deliverables:** ✅ +- ✅ Fix engineering#9 (spurious `this.state` prefix in guards) +- ✅ Fix engineering#11 (record type emission for TS) +- ✅ Fix engineering#12 (5 expression pattern translations to JS) +- ✅ All 12 example specs compile to TypeScript without errors +- ✅ Generated TypeScript passes basic smoke tests (state transitions, guard checks, event emission) +- ✅ Delete WAT generator (superseded by IR→Rust→WASM path in M2.1) -**Exit criteria:** `speckl compile examples/*.speck --target=typescript` produces `.ts` files that compile with `tsc --noEmit` and pass a generated test suite. +**Completed:** 2026-05-10. Branch `fix/ts-generator-bugs`, `fix/remove-wat-generator`. All 41 tests passing. --- -### M0.2 — Typed Intermediate Representation +### M0.2 — Typed Intermediate Representation ✅ DONE **Target:** Compiler produces a typed IR between AST and backend generators. No generator duplicates type logic or parses raw AST. **Dependencies:** M0.1 complete -**Deliverables:** -- Define IR schema: `SpeckIR` with typed state, actions, invariants, events, provenance annotations -- Refactor parser → `[AST] → type check → [SpeckIR]` pipeline -- All generators (TS, PROV-O, CycloneDX, SPDX) consume IR, not AST -- IR includes provenance annotations (source line → IR node mapping) +**Deliverables:** ✅ +- ✅ Define IR schema: `SpeckIR` with typed state, actions, invariants, events, provenance annotations +- ✅ Full pipeline: Parse → AST → TypeCheck → SpeckIR → Optimize → Backend Selection +- ✅ 4 optimization passes: guard elision, dead state elimination, transition tables, invariant hoisting +- ✅ 5-phase incremental migration plan (each generator migrates one at a time) +- ✅ Z3 translation mapping (SpeckDL → SMT-LIB sorts, assertions, BMC unrolling) +- ✅ Provenance annotations (SourceSpan → IR node → artifact) -**Exit criteria:** `speckl compile` produces IR as an intermediate artifact. Each generator consumes IR only. Provenance chain from source line to generated artifact is traceable. +**Completed:** 2026-05-10. Branch `feat/ir-design-speckl-20`. 1,106-line design doc at `docs/ir-design.md`. Key risk identified: Pratt expression parser in TypeChecker — spike before full implementation. --- @@ -74,22 +76,18 @@ The compiler must be able to accept real specs and produce verified artifacts. R The core deliverable: a complete, verified specification of Kafka's KRaft consensus protocol in SpeckDL. -### M1.1 — KRaft State Machine Specification +### M1.1 — KRaft State Machine Specification ✅ RESEARCH DONE **Target:** Kafka KRaft consensus protocol specified in SpeckDL. Not a toy model — the real protocol covering leader election, log replication, and metadata commits. **Dependencies:** M0.3 complete (need Z3 verification to validate the spec) -**Deliverables:** -- `examples/KafkaKRaft.speck` — full KRaft spec including: - - State: term, votedFor, log entries, commitIndex, leaderId, cluster metadata - - Actions: RequestVote, AppendEntries, Commit, BecomeLeader, BecomeFollower - - Invariants: log matching, leader completeness, term monotonicity, no uncommitted data loss - - Events: LeaderElected, LogReplicated, Committed, TermChanged -- Each action has `require` guards matching KRaft's actual preconditions -- Invariants are the ones cited in the original Raft paper (Ongaro dissertation) and KRaft Kafka documentation +**Research deliverables:** ✅ +- ✅ `docs/kraft-protocol-reference.md` — complete Raft TLA+ state machine reference with 10 actions, 6 safety invariants, KRaft extensions, producer ack semantics, and scope boundary +- ✅ All state variables with types, all transitions with preconditions +- ✅ Source citations for each element -**Exit criteria:** Spec compiles to TypeScript without errors. Z3 bounded verification runs without crashes. All invariants are stated and checkable. +**Remaining:** Write the actual `examples/KafkaKRaft.speck` spec (M1.2 dependency on Z3 backend M0.3, but spec can be written now) --- @@ -166,20 +164,18 @@ The Rust backend is the path to production-runnable verified code and WASM as a The spec and verification results become marketing assets. -### M3.1 — Blog Post: "We Formally Verified Kafka's Consensus" +### M3.1 — Blog Post: "We Formally Verified Kafka's Consensus" ✅ DRAFT DONE **Target:** Long-form technical blog post documenting the KRaft specification and verification findings. **Dependencies:** M1.2 complete (need results), M0.3 complete (need Z3 to explain) -**Deliverables:** -- Blog post on speckl.scoble.me (or scott.scoble.me if higher traffic) -- Structure: Problem → Method → Spec overview → Verification results → Findings → Implications -- Include the full `.speck` file inline (it's the hero artifact) -- If a real gap/vulnerability was found in M1.2, lead with that -- Cross-post to Hacker News, Reddit r/distributed_systems, Lobsters +**Deliverables:** ✅ +- ✅ `docs/blog-06-prove-kafka.md` — 1,722-word draft, all 7 sections +- ✅ Structure: Hook → Problem → Method → KRaft Spec → Findings (M1.2 placeholder) → Implications → CTA +- ✅ Written in Scott's voice (semicolons, no em dashes, evidence over assertion) -**Exit criteria:** Published blog post with working code examples. HN submission ready. +**Remaining:** Fill M1.2 verification results into findings section, then publish --- @@ -250,19 +246,18 @@ Once Kafka is proven, extend to other high-value targets. --- -### M4.3 — OAuth 2.0 / OIDC Flow Specification +### M4.3 — OAuth 2.0 / OIDC Flow Specification ✅ DONE **Target:** Specify the OAuth 2.0 authorization code flow (including PKCE) as a state machine and verify its invariants. **Dependencies:** M0.3 complete -**Deliverables:** -- `examples/OAuth2AuthorizationCode.speck` — full auth code flow with PKCE -- Invariants: no token leakage, CSRF protection, code reuse prevention, replay attack resistance -- Verification: prove that PKCE prevents authorization code interception -- Sales angle: "We proved OAuth works. Can we prove YOUR auth works?" +**Deliverables:** ✅ +- ✅ `examples/OAuth2AuthorizationCode.speck` — 6 actions, 7 invariants, PKCE modeled +- ✅ Invariants: NoTokenLeakage, StateCSRFProtection, AuthorizationCodeSingleUse, TokenValidityBounded, PKCECodeInterceptionPrevention, RedirectUriConsistency, ClientAuthenticationRequired +- Remaining: Z3 verification (depends on M0.3) -**Exit criteria:** OAuth spec compiles and verifies. At least one PKCE invariant proven. Marketing-ready asset. +**Completed:** 2026-05-10. Branch `feature/oauth2-spec`. ---