$ show vignesh07/clawdbot-formal-models
This repository is a formal verification suite for Clawdbot, a Discord bot, using TLA+ and the TLC model checker. It provides machine-checkable security models that act as a regression suite: 'green' models should pass (no invariant violation) and 'red' models are deliberately buggy variants that should fail with a counterexample trace. The repo includes over 100 TLA+ specifications covering gateway exposure, node command policy, pairing store invariants, routing isolation, Discord-specific conformance (role gating, PluralKit, thread binding), and liveness properties. It also contains scripts to extract tool group definitions from the main Clawdbot codebase and generate TLA+ configuration constants, ensuring conformance between the formal models and the implementation. The architecture is a collection of TLA+ specs and model configs orchestrated by a Makefile, with a vendored TLC jar and a CI pipeline that runs selected models on each PR. While the models are domain-specific to Clawdbot, the patterns (e.g., policy precedence, pairing store with expiry and cap, tokenized approvals) are reusable templates for formal verification of similar systems.
The LLM identified 4 files worth highlighting for reuse:
A robust shell script that locates a Java runtime (handling macOS stubs and Homebrew paths) and runs TLC with a timestamped metadir to avoid collisions. It is self-contained and can be reused in any TLA+ project that needs a reliable TLC launcher.
A Node.js script that extracts tool group definitions and aliases from the main Clawdbot TypeScript source (tool-policy.ts) and writes them as a JSON file. It handles project renames and ensures alias consistency. This pattern is reusable for any project that needs to generate conformance data from source code.
A TLA+ specification that models a layered tool policy with 'deny wins' monotonicity. It defines a recursive fold over allow/deny layers and checks that denied tools never appear in the final allowed set. This pattern is generic and can be adapted to any system with layered access control policies.
A TLA+ specification modeling a pairing store with per-channel pending caps, request expiry, and approval lifecycle. It checks invariants like no approval of expired requests and pending cap enforcement. The model is well-structured and can serve as a template for verifying similar store semantics in other systems.