git404hub

what is dspec fr?

mizchi/dspec — explained in plain English

Analysis updated 2026-05-18

32JavaScriptAudience · researcherComplexity · 5/5Setup · hard

tl;dr

An early prototype toolkit for writing software specifications in a typed language that can be checked, rendered, and formally verified.

vibe map

mindmap
  root((dspec))
    What it does
      Executable specs
      Consistency checks
      Drift detection
    Tech stack
      Pkl
      Node.js
      TLA+ Alloy Z3 Lean
    Use cases
      Check spec consistency
      Compare spec versions
      Formal verification
    Setup
      Nix dev shell
      Multiple formal tools
    Audience
      Researchers
      Spec driven developers

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Write a software specification in a typed language and check it for internal consistency.

VIBE 2

Compare two versions of a spec to see whether a change is backward compatible or breaking.

VIBE 3

Import facts from a real running application and compare them against a written spec.

VIBE 4

Formally verify properties of a specification using tools like TLA+, Alloy, Z3, or Lean.

what's the stack?

JavaScriptNode.jsPklTLA+AlloyZ3Lean

how it stacks up fr

mizchi/dspeca6216abcd/free-residential-ip-proxy-controllerearthtojake/cad-viewer
Stars323232
LanguageJavaScriptJavaScriptJavaScript
Setup difficultyhardhardmoderate
Complexity5/54/53/5
Audienceresearcherdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · hard time til it works · 1h+

Requires the Nix package manager to provide Pkl, Lean, Z3, TLA+, and Alloy together.

in plain english

This project is an early prototype of a system for writing software specifications that a computer can actually check and run, instead of specifications that are just plain text documents nobody verifies. It uses a typed configuration language called Pkl to author the specification, so mistakes in the spec's structure get caught early, before that spec is compared against real code or real behavior. The core idea is that a spec written in Pkl has a stable schema and unique ids for each piece, and from that structured spec the tool can generate a natural language description in different languages, check whether a real application matches what the spec describes, and detect drift when the spec and the implementation fall out of sync over time. The command line tool included in the project offers a very large number of operations: checking a spec file for consistency, rendering it as readable text, comparing two versions of a spec to see if a change is backward compatible or breaking, importing facts from a real running application to compare against the spec, and generating structured reports and coverage numbers about how much of a spec has been verified. For deeper formal verification, the project can hook into established tools from computer science research, including TLA+, Alloy, Z3, and Lean, which are used to mathematically prove properties about a system rather than just testing it. This is an early, experimental prototype rather than a finished product, and it currently requires the Nix package manager to set up its development environment with all the required tools installed together. It is aimed at developers and researchers who work on specification-driven or formally verified software, not general audiences. The full README is longer than what was shown.

prompts (copy fr)

prompt 1
Help me set up the Nix dev shell for dspec and run its test suite.
prompt 2
Explain what an executable specification is and how dspec's Pkl based approach differs from plain documentation.
prompt 3
Walk me through checking one of the example specs in this repo with the dspec CLI.
prompt 4
How does dspec detect drift between a written spec and a real application?
prompt 5
Explain how dspec integrates with formal verification tools like TLA+ and Z3.

Frequently asked questions

what is dspec fr?

An early prototype toolkit for writing software specifications in a typed language that can be checked, rendered, and formally verified.

What language is dspec written in?

Mainly JavaScript. The stack also includes JavaScript, Node.js, Pkl.

How hard is dspec to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is dspec for?

Mainly researcher.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.