EXPLAINME.adoc

WokeLang — Show Me The Receipts

The README makes claims about a human-centered programming language with a Rust compiler, consent gates, unit types, and blockchain FFI. This file backs them up with specific module paths, data-flow through the compiler pipeline, and honest notes about what is a working implementation vs. a design commitment.

What WokeLang Is

WokeLang is a standalone language in the hyperpolymath estate, designed around three principles: human-readable syntax (English-like keywords), ethical scaffolding (consent gates, gratitude blocks, empathy annotations), and type safety with dimensional analysis (units of measure enforced at compile time). The primary implementation is a Rust compiler/interpreter (src/, Cargo.toml) that runs WokeLang programs via a tree-walking interpreter or compiles them to bytecode for the WokeLang VM. A WASM target is a design commitment (see Claim 2). An OCaml reference core (core/, built with dune + menhir) provides an independent AST + evaluator pipeline used for research, semantics cross-checking, and the end-to-end CI gate. (Note: wokelang.opam is currently an intentionally empty stub; the OCaml core builds from dune-project.)

The frontier workstream integrates echo types — hyperpolymath/echo-types, a constructive Agda formalization of fiber-based structured loss — into the type checker, backed by a near-first-principles machine-checked proof narrative (Isabelle preferred), so the language discharges consent / affine-use safety for the user automatically.

Claim 1: Rust compiler with lexer, parser, type checker, and VM

WokeLang is a programming language designed for human collaboration, empathy, and safety — without sacrificing power or performance. It combines Python’s readability with Rust’s performance. Hindley-Milner type inference with JavaScript’s expressiveness.

— README

How it works. The Rust compiler pipeline in src/ follows this data path:

1. src/lexer/ (mod.rs, token.rs) — tokenises .woke source text into a Token stream including WokeLang-specific tokens (remember, measured in, only if okay, thanks to, then).

2. src/parser/ — recursive-descent parser producing a WokeLang-specific AST (src/ast/).

3. src/typechecker/mod.rs — static type inference; the Unit enum encodes dimensional analysis (Meter, Kilogram, Second, etc.) so that 5 measured in km + 3 measured in km is valid but 5 measured in km + 3 measured in kg is a type error at compile time. The TypeError type carries a message string and implements std::error::Error.

4. src/interpreter/ — tree-walking interpreter for woke run.

5. src/vm/ (machine.rs, compiler.rs, bytecode.rs, optimizer.rs) — bytecode compiler and stack VM for woke compile + woke run-vm.

6. src/codegen/ — WASM code generation target.

7. src/main.rs — CLI entry point using clap; subcommands run, repl, compile, run-vm, disassemble, check, lint, format.

8. src/repl.rs — interactive REPL loop.

src/lsp/ provides a Language Server Protocol implementation for editor integration, and src/dap/ provides a Debug Adapter Protocol implementation.

Honest caveat. The type checker currently implements a simplified form of Hindley-Milner inference — the README’s claim of full HM unification applies to scalar types and unit types, but full polymorphic inference over closures and module types is a roadmap item. PROOF-NEEDS.md and PHRONESIS-ALIGNMENT-GAP.md document the outstanding obligations.

Claim 2: Vyper FFI and WASM target for blockchain operations

Vyper FFI: vyper call "gratitude.add_entry" — immutable, auditable blockchain ops. WASM Target: Compile to run in browsers/Node.js. Portable and fast.

— README

How it works (and what is real). src/codegen/ declares a WasmCompiler scaffold for a future WASM backend. examples/ contains .woke files demonstrating the implemented feature set including only if okay consent gates (08_consent.woke, 22_consent_system.woke), thanks to gratitude blocks (17_gratitude.woke), and security examples. src/stdlib/ provides the standard library (array, chan, io, json, math, net, string, time), where io and net route side effects through the consent machinery. fuzz/ contains fuzzing harnesses (driven by ClusterFuzzLite in CI). verification/ holds formal verification artefacts.

Honest caveat. The Vyper / blockchain FFI and the WASM target are design commitments described in the README feature table, the language spec, and the research paper — they are not working implementations in the current tree. There is no vyper bridge in src/stdlib/, and the src/codegen/ WASM module is a scaffold that is not yet wired into the build or emitting binaries. Treat both as research capabilities on the roadmap, not production-ready integrations.

Dogfooded Across The Account

Tool / Repo	How wokelang uses it
panic-attacker	Pre-commit security scan gate (just pre-commit)
contractile.just / contractiles	Standard hyperpolymath contractile integration
stapeln.toml	Container build manifest for the WokeLang compiler image (Chainguard Wolfi base)
nextgen-languages	Sibling estate (home of AffineScript / my-lang). WokeLang is a standalone repository in the hyperpolymath estate, not a submodule of nextgen-languages.
ABI-FFI-README.md	Account-wide ABI/FFI convention applied: src/abi/ holds the Idris2 ABI definitions (Foreign.idr, Layout.idr, Types.idr) and src/ffi/ holds the Rust C-ABI bridge (c_api.rs).
grammar/	WokeLang grammar source feeding editor syntax support (TextMate / tree-sitter).
editors/	Editor integration: a TextMate grammar plus a VS Code extension. The VS Code extension is currently syntax-only — its ReScript LSP client was removed (banned estate-wide) and an AffineScript reimplementation is tracked in issue #78. The Rust woke-lsp server binary is unaffected and works with any LSP-capable editor.
arxiv-consent-aware-programming.tex	Research paper on consent-aware programming; wokelang is the reference implementation
hypatia	Hypatia CI checks for banned language patterns and dangerous unsafe usage

File Map

Path	What’s There
src/main.rs	CLI entry point: clap-based subcommand dispatch (run, repl, compile, run-vm, disassemble, check, lint, format)
src/lexer/mod.rs + token.rs	Tokeniser: WokeLang-specific tokens including remember, measured in, only if okay, thanks to, then
src/parser/	Recursive-descent parser producing the WokeLang AST
src/ast/	AST node definitions: all statement, expression, and declaration node types
src/typechecker/mod.rs	Type inference: Unit enum for dimensional analysis, TypeError, simplified HM inference for scalars
src/interpreter/	Tree-walking interpreter: evaluates typed AST directly for woke run
src/vm/machine.rs	Stack-based bytecode VM: instruction execution, call stack management
src/vm/compiler.rs	AST-to-bytecode compiler: lowers typed AST to WokeLang bytecode
src/vm/bytecode.rs	Bytecode instruction set definition
src/vm/optimizer.rs	Bytecode optimiser: constant folding, dead code elimination
src/codegen/	Code-generation scaffolding (WasmCompiler); a future WASM backend, not yet wired into the build
src/lsp/	Language Server Protocol implementation (built as the woke-lsp binary)
src/dap/	Debug Adapter Protocol implementation (built as the woke-dap binary)
src/repl.rs	Interactive REPL loop
src/sexpr.rs	S-expression AST dump (for debugging and tooling)
src/stdlib/	Standard library: array, chan, io, json, math, net, string, time (consent-routed I/O and networking)
src/linter/	Static linter: style rules, consent-gate usage checks
src/formatter/	Code formatter: canonical WokeLang style
src/security/	Security analysis passes: dangerous operation detection
src/modules.rs	Module system: import resolution and namespace management
src/abi/	Idris2 ABI definitions (Foreign.idr, Layout.idr, Types.idr, wokelang-abi.ipkg) for the FFI boundary
src/ffi/	Rust C-ABI FFI bridge (c_api.rs, mod.rs)
grammar/	Tree-sitter grammar source for WokeLang syntax
editors/	TextMate grammar + VS Code extension (currently syntax-only; ReScript LSP client removed, AffineScript reimpl tracked in issue #78)
examples/	.woke example programs: hello world through fibonacci, unit arithmetic, consent gates, gratitude blocks
spec/	Language specification documents
verification/	Formal verification artefacts for core language properties
fuzz/	Fuzzing harnesses for parser and typechecker
bench/ / benches/	Criterion benchmarks: interpreter and VM throughput
core/	OCaml reference core: lexer.mll (ocamllex) + parser.mly (menhir) + ast.ml + eval.ml, built with dune
compiler/wokelang-wasm/	Standalone Rust crate for the WASM compilation experiment (lib.rs)
conformance/	Conformance test suite against the language specification
site/	Language documentation website source
arxiv-consent-aware-programming.tex	Research paper: WokeLang as reference implementation for consent-aware programming
Cargo.toml	Rust workspace manifest
dune-project / wokelang.opam	OCaml build configuration for the core/ reference (dune-project drives the build; wokelang.opam is currently an empty stub)
Justfile / Mustfile	Developer recipes: build, test, bench, fuzz, check-conformance
PROOF-NEEDS.md	Outstanding formal proof obligations
PHRONESIS-ALIGNMENT-GAP.md	Documents gaps between stated design principles and current implementation
TOOLCHAIN-WISHLIST.md	Desired toolchain improvements (Idris2 type-checker integration, full HM)
stapeln.toml	Container build manifest
flake.nix / guix.scm	Reproducible build environments (Rust + OCaml toolchain); Guix primary, Nix fallback

Questions?

Open an issue or reach out directly — happy to explain anything in more detail.

License

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: CC-BY-SA-4.0