From 5de596c544808a70f87ddbe591ca04ecb0892f2a Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Mon, 24 Aug 2026 08:53:07 +0100
Subject: [PATCH] refactor: migrate repository documentation from Markdown to
AsciiDoc
---
ABI-FFI-README.md => ABI-FFI-README.adoc | 244 ++++---
ARCHITECTURE.adoc | 48 ++
ARCHITECTURE.md | 47 --
CHANGELOG.adoc | 14 +
CHANGELOG.md | 16 -
CODE_OF_CONDUCT.adoc | 339 ++++++++++
CODE_OF_CONDUCT.md | 312 ---------
CONTRIBUTING.adoc | 35 +-
CONTRIBUTING.md | 29 -
GOVERNANCE.adoc | 178 ++---
GOVERNANCE.md | 60 --
MAINTAINERS.adoc | 41 +-
MAINTAINERS.md | 51 --
PHRONESIS-ALIGNMENT-GAP.adoc | 432 ++++++++++++
PHRONESIS-ALIGNMENT-GAP.md | 503 --------------
PROOF-NEEDS.adoc | 51 ++
PROOF-NEEDS.md | 40 --
RESUME.adoc | 151 +++++
RESUME.md | 124 ----
SECURITY.adoc | 16 +
SECURITY.md | 23 -
TEST-NEEDS.adoc | 187 +++++
TEST-NEEDS.md | 156 -----
TOOLCHAIN-WISHLIST.adoc | 582 ++++++++++++++++
TOOLCHAIN-WISHLIST.md | 638 ------------------
TOPOLOGY.md => TOPOLOGY.adoc | 43 +-
docs/NEXT-CLAUDE-PROMPT.adoc | 70 ++
docs/NEXT-CLAUDE-PROMPT.md | 72 --
docs/PROVEN.adoc | 94 +++
docs/PROVEN.md | 91 ---
docs/ROADMAP.adoc | 331 +++++++++
docs/ROADMAP.md | 295 --------
docs/core/INDEX.adoc | 76 +++
docs/core/INDEX.md | 74 --
docs/core/{SETUP.md => SETUP.adoc} | 128 ++--
docs/proofs/README.adoc | 90 +++
docs/proofs/README.md | 68 --
docs/proofs/VERIFICATION-ROADMAP.adoc | 318 +++++++++
docs/proofs/VERIFICATION-ROADMAP.md | 213 ------
docs/proofs/compiler/memory-model.adoc | 445 ++++++++++++
docs/proofs/compiler/memory-model.md | 425 ------------
.../compiler/semantic-preservation.adoc | 537 +++++++++++++++
docs/proofs/compiler/semantic-preservation.md | 511 --------------
.../complexity/complexity-analysis.adoc | 421 ++++++++++++
docs/proofs/complexity/complexity-analysis.md | 425 ------------
docs/proofs/concurrency/worker-safety.adoc | 470 +++++++++++++
docs/proofs/concurrency/worker-safety.md | 474 -------------
...mantics.md => denotational-semantics.adoc} | 339 +++++-----
.../formal-semantics/grammar-proofs.adoc | 493 ++++++++++++++
.../proofs/formal-semantics/grammar-proofs.md | 454 -------------
...emantics.md => operational-semantics.adoc} | 382 ++++++-----
.../papers/language-design-whitepaper.adoc | 379 +++++++++++
.../papers/language-design-whitepaper.md | 335 ---------
...guage-design-whitepaper.md.invariants.adoc | 2 +
...anguage-design-whitepaper.md.invariants.md | 7 -
docs/proofs/security/capability-proofs.adoc | 425 ++++++++++++
docs/proofs/security/capability-proofs.md | 391 -----------
docs/proofs/security/consent-model.adoc | 442 ++++++++++++
docs/proofs/security/consent-model.md | 395 -----------
...ns.md => category-theory-foundations.adoc} | 389 +++++------
...{hindley-milner.md => hindley-milner.adoc} | 316 +++++----
docs/proofs/type-theory/type-safety.adoc | 443 ++++++++++++
docs/proofs/type-theory/type-safety.md | 415 ------------
docs/proofs/verification/AUDIT.adoc | 340 ++++++++++
docs/proofs/verification/AUDIT.md | 290 --------
.../verification/GRAMMAR-PROOF-INVENTORY.adoc | 338 ++++++++++
.../verification/GRAMMAR-PROOF-INVENTORY.md | 241 -------
docs/reports/audit/audit-2026-04-04.adoc | 137 ++++
docs/reports/audit/audit-2026-04-04.md | 103 ---
docs/tech-debt-2026-05-26.adoc | 80 +++
docs/tech-debt-2026-05-26.md | 70 --
editors/vscode/README.adoc | 79 +++
editors/vscode/README.md | 78 ---
examples/README.adoc | 110 +++
examples/README.md | 94 ---
lib/README.adoc | 134 ++++
lib/README.md | 132 ----
lib/common/README.adoc | 86 +++
lib/common/README.md | 67 --
lib/wokelang/README.adoc | 107 +++
lib/wokelang/README.md | 96 ---
llm-warmup-dev.adoc | 19 +
llm-warmup-dev.md | 20 -
llm-warmup-user.adoc | 19 +
llm-warmup-user.md | 20 -
site/index.adoc | 28 +
site/index.md | 26 -
...-semantics.md => axiomatic-semantics.adoc} | 147 ++--
spec/system-specs.adoc | 96 +++
spec/system-specs.md | 91 ---
90 files changed, 9537 insertions(+), 9106 deletions(-)
rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%)
create mode 100644 ARCHITECTURE.adoc
delete mode 100644 ARCHITECTURE.md
create mode 100644 CHANGELOG.adoc
delete mode 100644 CHANGELOG.md
create mode 100644 CODE_OF_CONDUCT.adoc
delete mode 100644 CODE_OF_CONDUCT.md
delete mode 100644 CONTRIBUTING.md
delete mode 100644 GOVERNANCE.md
delete mode 100644 MAINTAINERS.md
create mode 100644 PHRONESIS-ALIGNMENT-GAP.adoc
delete mode 100644 PHRONESIS-ALIGNMENT-GAP.md
create mode 100644 PROOF-NEEDS.adoc
delete mode 100644 PROOF-NEEDS.md
create mode 100644 RESUME.adoc
delete mode 100644 RESUME.md
create mode 100644 SECURITY.adoc
delete mode 100644 SECURITY.md
create mode 100644 TEST-NEEDS.adoc
delete mode 100644 TEST-NEEDS.md
create mode 100644 TOOLCHAIN-WISHLIST.adoc
delete mode 100644 TOOLCHAIN-WISHLIST.md
rename TOPOLOGY.md => TOPOLOGY.adoc (81%)
create mode 100644 docs/NEXT-CLAUDE-PROMPT.adoc
delete mode 100644 docs/NEXT-CLAUDE-PROMPT.md
create mode 100644 docs/PROVEN.adoc
delete mode 100644 docs/PROVEN.md
create mode 100644 docs/ROADMAP.adoc
delete mode 100644 docs/ROADMAP.md
create mode 100644 docs/core/INDEX.adoc
delete mode 100644 docs/core/INDEX.md
rename docs/core/{SETUP.md => SETUP.adoc} (56%)
create mode 100644 docs/proofs/README.adoc
delete mode 100644 docs/proofs/README.md
create mode 100644 docs/proofs/VERIFICATION-ROADMAP.adoc
delete mode 100644 docs/proofs/VERIFICATION-ROADMAP.md
create mode 100644 docs/proofs/compiler/memory-model.adoc
delete mode 100644 docs/proofs/compiler/memory-model.md
create mode 100644 docs/proofs/compiler/semantic-preservation.adoc
delete mode 100644 docs/proofs/compiler/semantic-preservation.md
create mode 100644 docs/proofs/complexity/complexity-analysis.adoc
delete mode 100644 docs/proofs/complexity/complexity-analysis.md
create mode 100644 docs/proofs/concurrency/worker-safety.adoc
delete mode 100644 docs/proofs/concurrency/worker-safety.md
rename docs/proofs/formal-semantics/{denotational-semantics.md => denotational-semantics.adoc} (74%)
create mode 100644 docs/proofs/formal-semantics/grammar-proofs.adoc
delete mode 100644 docs/proofs/formal-semantics/grammar-proofs.md
rename docs/proofs/formal-semantics/{operational-semantics.md => operational-semantics.adoc} (66%)
create mode 100644 docs/proofs/papers/language-design-whitepaper.adoc
delete mode 100644 docs/proofs/papers/language-design-whitepaper.md
create mode 100644 docs/proofs/papers/language-design-whitepaper.md.invariants.adoc
delete mode 100644 docs/proofs/papers/language-design-whitepaper.md.invariants.md
create mode 100644 docs/proofs/security/capability-proofs.adoc
delete mode 100644 docs/proofs/security/capability-proofs.md
create mode 100644 docs/proofs/security/consent-model.adoc
delete mode 100644 docs/proofs/security/consent-model.md
rename docs/proofs/type-theory/{category-theory-foundations.md => category-theory-foundations.adoc} (53%)
rename docs/proofs/type-theory/{hindley-milner.md => hindley-milner.adoc} (57%)
create mode 100644 docs/proofs/type-theory/type-safety.adoc
delete mode 100644 docs/proofs/type-theory/type-safety.md
create mode 100644 docs/proofs/verification/AUDIT.adoc
delete mode 100644 docs/proofs/verification/AUDIT.md
create mode 100644 docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.adoc
delete mode 100644 docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md
create mode 100644 docs/reports/audit/audit-2026-04-04.adoc
delete mode 100644 docs/reports/audit/audit-2026-04-04.md
create mode 100644 docs/tech-debt-2026-05-26.adoc
delete mode 100644 docs/tech-debt-2026-05-26.md
create mode 100644 editors/vscode/README.adoc
delete mode 100644 editors/vscode/README.md
create mode 100644 examples/README.adoc
delete mode 100644 examples/README.md
create mode 100644 lib/README.adoc
delete mode 100644 lib/README.md
create mode 100644 lib/common/README.adoc
delete mode 100644 lib/common/README.md
create mode 100644 lib/wokelang/README.adoc
delete mode 100644 lib/wokelang/README.md
create mode 100644 llm-warmup-dev.adoc
delete mode 100644 llm-warmup-dev.md
create mode 100644 llm-warmup-user.adoc
delete mode 100644 llm-warmup-user.md
create mode 100644 site/index.adoc
delete mode 100644 site/index.md
rename spec/{axiomatic-semantics.md => axiomatic-semantics.adoc} (75%)
create mode 100644 spec/system-specs.adoc
delete mode 100644 spec/system-specs.md
diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc
similarity index 74%
rename from ABI-FFI-README.md
rename to ABI-FFI-README.adoc
index 2849272..6e0aa1a 100644
--- a/ABI-FFI-README.md
+++ b/ABI-FFI-README.adoc
@@ -1,23 +1,22 @@
-
-{{~ Aditionally delete this line and fill out the template below ~}}
+\{\{~ Aditionally delete this line and fill out the template below ~}}
-# WOKELANG ABI/FFI Documentation
+== WOKELANG ABI/FFI Documentation
-## Overview
+=== Overview
-This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
+This library follows the *Hyperpolymath RSR Standard* for ABI and FFI
+design:
-- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs
-- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility
-- **Generated C headers** bridge Idris2 ABI to Zig FFI
-- **Any language** can call through standard C ABI
+* *ABI (Application Binary Interface)* defined in *Idris2* with formal
+proofs
+* *FFI (Foreign Function Interface)* implemented in *Zig* for C
+compatibility
+* *Generated C headers* bridge Idris2 ABI to Zig FFI
+* *Any language* can call through standard C ABI
-## Architecture
+=== Architecture
-```
+....
┌─────────────────────────────────────────────┐
│ ABI Definitions (Idris2) │
│ src/abi/ │
@@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
│ Any Language via C ABI │
│ - Rust, ReScript, Julia, Python, etc. │
└─────────────────────────────────────────────┘
-```
+....
-## Directory Structure
+=== Directory Structure
-```
+....
wokelang/
├── src/
│ ├── abi/ # ABI definitions (Idris2)
@@ -81,15 +80,17 @@ wokelang/
├── rust/
├── rescript/
└── julia/
-```
+....
-## Why Idris2 for ABI?
+=== Why Idris2 for ABI?
-### 1. **Formal Verification**
+==== 1. *Formal Verification*
-Idris2's dependent types allow proving properties about the ABI at compile-time:
+Idris2’s dependent types allow proving properties about the ABI at
+compile-time:
-```idris
+[source,idris]
+----
-- Prove struct size is correct
public export
exampleStructSize : HasSize ExampleStruct 16
@@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field)
-- Prove ABI is platform-compatible
public export
abiCompatible : Compatible (ABI 1) (ABI 2)
-```
+----
-### 2. **Type Safety**
+==== 2. *Type Safety*
Encode invariants that C/Zig cannot express:
-```idris
+[source,idris]
+----
-- Non-null pointer guaranteed at type level
data Handle : Type where
MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle
@@ -115,13 +117,14 @@ data Handle : Type where
-- Array with length proof
data Buffer : (n : Nat) -> Type where
MkBuffer : Vect n Byte -> Buffer n
-```
+----
-### 3. **Platform Abstraction**
+==== 3. *Platform Abstraction*
Platform-specific types with compile-time selection:
-```idris
+[source,idris]
+----
CInt : Platform -> Type
CInt Linux = Bits32
CInt Windows = Bits32
@@ -129,13 +132,14 @@ CInt Windows = Bits32
CSize : Platform -> Type
CSize Linux = Bits64
CSize Windows = Bits64
-```
+----
-### 4. **Safe Evolution**
+==== 4. *Safe Evolution*
Prove that new ABI versions are backward-compatible:
-```idris
+[source,idris]
+----
-- Compiler enforces compatibility
abiUpgrade : ABI 1 -> ABI 2
abiUpgrade old = MkABI2 {
@@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 {
-- Can add new fields
new_features = defaults
}
-```
+----
-## Why Zig for FFI?
+=== Why Zig for FFI?
-### 1. **C ABI Compatibility**
+==== 1. *C ABI Compatibility*
Zig exports C-compatible functions naturally:
-```zig
+[source,zig]
+----
export fn library_function(param: i32) i32 {
return param * 2;
}
-```
+----
-### 2. **Memory Safety**
+==== 2. *Memory Safety*
Compile-time safety without runtime overhead:
-```zig
+[source,zig]
+----
// Null check enforced at compile time
const handle = init() orelse return error.InitFailed;
defer free(handle);
-```
+----
-### 3. **Cross-Compilation**
+==== 3. *Cross-Compilation*
Built-in cross-compilation to any platform:
-```bash
+[source,bash]
+----
zig build -Dtarget=x86_64-linux
zig build -Dtarget=aarch64-macos
zig build -Dtarget=x86_64-windows
-```
+----
-### 4. **Zero Dependencies**
+==== 4. *Zero Dependencies*
No runtime, no libc required (unless explicitly needed):
-```zig
+[source,zig]
+----
// Minimal binary size
pub const lib = @import("std");
// Only includes what you use
-```
+----
-## Building
+=== Building
-### Build FFI Library
+==== Build FFI Library
-```bash
+[source,bash]
+----
cd ffi/zig
zig build # Build debug
zig build -Doptimize=ReleaseFast # Build optimized
zig build test # Run tests
-```
+----
-### Generate C Header from Idris2 ABI
+==== Generate C Header from Idris2 ABI
-```bash
+[source,bash]
+----
cd src/abi
idris2 --cg c-header Types.idr -o ../../generated/abi/wokelang.h
-```
+----
-### Cross-Compile
+==== Cross-Compile
-```bash
+[source,bash]
+----
cd ffi/zig
# Linux x86_64
@@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos
# Windows x86_64
zig build -Dtarget=x86_64-windows
-```
+----
-## Usage
+=== Usage
-### From C
+==== From C
-```c
+[source,c]
+----
#include "wokelang.h"
int main() {
@@ -241,16 +253,19 @@ int main() {
wokelang_free(handle);
return 0;
}
-```
+----
Compile with:
-```bash
+
+[source,bash]
+----
gcc -o example example.c -lwokelang -L./zig-out/lib
-```
+----
-### From Idris2
+==== From Idris2
-```idris
+[source,idris]
+----
import WOKELANG.ABI.Foreign
main : IO ()
@@ -263,11 +278,12 @@ main = do
free handle
putStrLn "Success"
-```
+----
-### From Rust
+==== From Rust
-```rust
+[source,rust]
+----
#[link(name = "wokelang")]
extern "C" {
fn wokelang_init() -> *mut std::ffi::c_void;
@@ -286,11 +302,12 @@ fn main() {
wokelang_free(handle);
}
}
-```
+----
-### From Julia
+==== From Julia
-```julia
+[source,julia]
+----
const libwokelang = "libwokelang"
function init()
@@ -316,27 +333,30 @@ try
finally
cleanup(handle)
end
-```
+----
-## Testing
+=== Testing
-### Unit Tests (Zig)
+==== Unit Tests (Zig)
-```bash
+[source,bash]
+----
cd ffi/zig
zig build test
-```
+----
-### Integration Tests
+==== Integration Tests
-```bash
+[source,bash]
+----
cd ffi/zig
zig build test-integration
-```
+----
-### ABI Verification (Idris2)
+==== ABI Verification (Idris2)
-```idris
+[source,idris]
+----
-- Compile-time verification
%runElab verifyABI
@@ -346,44 +366,44 @@ main = do
verifyLayoutsCorrect
verifyAlignmentsCorrect
putStrLn "ABI verification passed"
-```
+----
-## Contributing
+=== Contributing
When modifying the ABI/FFI:
-1. **Update ABI first** (`src/abi/*.idr`)
- - Modify type definitions
- - Update proofs
- - Ensure backward compatibility
-
-2. **Generate C header**
- ```bash
- idris2 --cg c-header src/abi/Types.idr -o generated/abi/wokelang.h
- ```
-
-3. **Update FFI implementation** (`ffi/zig/src/main.zig`)
- - Implement new functions
- - Match ABI types exactly
-
-4. **Add tests**
- - Unit tests in Zig
- - Integration tests
- - ABI verification tests
-
-5. **Update documentation**
- - Function signatures
- - Usage examples
- - Migration guide (if breaking changes)
-
-## License
+[arabic]
+. *Update ABI first* (`+src/abi/*.idr+`)
+* Modify type definitions
+* Update proofs
+* Ensure backward compatibility
+. *Generate C header*
++
+[source,bash]
+----
+idris2 --cg c-header src/abi/Types.idr -o generated/abi/wokelang.h
+----
+. *Update FFI implementation* (`+ffi/zig/src/main.zig+`)
+* Implement new functions
+* Match ABI types exactly
+. *Add tests*
+* Unit tests in Zig
+* Integration tests
+* ABI verification tests
+. *Update documentation*
+* Function signatures
+* Usage examples
+* Migration guide (if breaking changes)
+
+=== License
MPL-2.0
-## See Also
+=== See Also
-- [Idris2 Documentation](https://idris2.readthedocs.io)
-- [Zig Documentation](https://ziglang.org/documentation/master/)
-- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories)
-- [FFI Migration Guide](../ffi-migration-guide.md)
-- [ABI Migration Guide](../abi-migration-guide.md)
+* https://idris2.readthedocs.io[Idris2 Documentation]
+* https://ziglang.org/documentation/master/[Zig Documentation]
+* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium
+Standard Repositories]
+* link:../ffi-migration-guide.md[FFI Migration Guide]
+* link:../abi-migration-guide.md[ABI Migration Guide]
diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc
new file mode 100644
index 0000000..1c0a7a6
--- /dev/null
+++ b/ARCHITECTURE.adoc
@@ -0,0 +1,48 @@
+== Architecture
+
+=== Overview
+
+This repository follows a modular, maintainable architecture designed
+for clarity, scalability, and long-term sustainability.
+
+=== Directory Structure
+
+....
+.
+├── src/ # Source code
+├── tests/ # Test suites
+├── docs/ # Documentation
+├── scripts/ # Utility scripts
+├── config/ # Configuration files
+├── LICENSE # License file
+├── LICENSES/ # Full license texts
+└── README.adoc # Project documentation
+....
+
+=== Design Principles
+
+* *Separation of Concerns*: Each module has a single responsibility
+* *Testability*: Code is written to be easily testable
+* *Documentation*: All public APIs are documented
+* *Configuration*: Environment-specific settings are externalized
+
+=== Dependencies
+
+* External dependencies are minimized and clearly declared
+* Version pinning is used for reproducibility
+
+=== Security Considerations
+
+* Sensitive data is never committed to the repository
+* Secrets are managed through environment variables or secure vaults
+* Regular dependency audits are performed
+
+=== Maintainability
+
+* Code follows consistent style guidelines
+* Pull requests require review and CI checks
+* Issues and discussions are tracked transparently
+
+'''''
+
+_Last updated: 2026-07-18_
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
deleted file mode 100644
index 607e3d8..0000000
--- a/ARCHITECTURE.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Architecture
-
-## Overview
-
-This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability.
-
-## Directory Structure
-
-```
-.
-├── src/ # Source code
-├── tests/ # Test suites
-├── docs/ # Documentation
-├── scripts/ # Utility scripts
-├── config/ # Configuration files
-├── LICENSE # License file
-├── LICENSES/ # Full license texts
-└── README.adoc # Project documentation
-```
-
-## Design Principles
-
-- **Separation of Concerns**: Each module has a single responsibility
-- **Testability**: Code is written to be easily testable
-- **Documentation**: All public APIs are documented
-- **Configuration**: Environment-specific settings are externalized
-
-## Dependencies
-
-- External dependencies are minimized and clearly declared
-- Version pinning is used for reproducibility
-
-## Security Considerations
-
-- Sensitive data is never committed to the repository
-- Secrets are managed through environment variables or secure vaults
-- Regular dependency audits are performed
-
-## Maintainability
-
-- Code follows consistent style guidelines
-- Pull requests require review and CI checks
-- Issues and discussions are tracked transparently
-
----
-
-*Last updated: 2026-07-18*
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
new file mode 100644
index 0000000..8ba87ef
--- /dev/null
+++ b/CHANGELOG.adoc
@@ -0,0 +1,14 @@
+== Changelog
+
+=== [Unreleased]
+
+==== Fixed
+
+* Restored README.adoc (accidentally deleted during RSR setup)
+* RSR compliance: standard file structure
+
+==== Added
+
+* SECURITY.md, 0-AI-MANIFEST.a2ml
+* Pandoc conformance tests (38 tests)
+* AST visitor framework
diff --git a/CHANGELOG.md b/CHANGELOG.md
deleted file mode 100644
index e52fde8..0000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,16 +0,0 @@
-
-# Changelog
-
-## [Unreleased]
-
-### Fixed
-- Restored README.adoc (accidentally deleted during RSR setup)
-- RSR compliance: standard file structure
-
-### Added
-- SECURITY.md, 0-AI-MANIFEST.a2ml
-- Pandoc conformance tests (38 tests)
-- AST visitor framework
diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc
new file mode 100644
index 0000000..06d592e
--- /dev/null
+++ b/CODE_OF_CONDUCT.adoc
@@ -0,0 +1,339 @@
+== Code of Conduct
+
+=== Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+wokelang a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, caste, colour, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+We recognise that a thriving open source community requires
+*psychological safety* — an environment where people can contribute, ask
+questions, make mistakes, and learn without fear of ridicule or
+retaliation.
+
+'''''
+
+=== Our Standards
+
+==== Expected Behaviour
+
+The following behaviours contribute to a positive environment:
+
+*Communication* - Using welcoming and inclusive language - Being
+respectful of differing viewpoints and experiences - Giving and
+gracefully accepting constructive feedback - Assuming good intent while
+addressing impact - Communicating clearly and patiently, especially with
+newcomers
+
+*Collaboration* - Focusing on what is best for the community - Showing
+empathy and kindness toward other community members - Being
+collaborative rather than competitive - Mentoring and supporting less
+experienced contributors - Celebrating others’ contributions and
+successes
+
+*Professionalism* - Accepting responsibility and apologising to those
+affected by our mistakes - Learning from the experience and avoiding
+repetition - Respecting others’ time and attention - Staying on topic in
+project spaces - Following project guidelines and conventions
+
+*Accessibility* - Using plain language and avoiding unnecessary jargon -
+Providing alt text for images and transcripts for audio/video - Being
+patient with those using assistive technologies - Accommodating
+different communication styles and needs - Recognising that not everyone
+communicates the same way
+
+==== Unacceptable Behaviour
+
+The following behaviours are considered harassment and are unacceptable:
+
+*Harassment* - The use of sexualised language or imagery, and sexual
+attention or advances of any kind - Trolling, insulting or derogatory
+comments, and personal or political attacks - Public or private
+harassment - Deliberate intimidation, stalking, or following (online or
+in-person) - Unwelcome physical contact or simulated physical contact
+(e.g., emoji) - Sustained disruption of talks, events, or online
+discussions
+
+*Discrimination* - Discriminatory jokes and language - Posting or
+threatening to post others’ personally identifying information
+("`doxing`") - Advocating for, or encouraging, any of the above
+behaviour - Microaggressions — subtle, often unintentional,
+discriminatory comments or actions
+
+*Professional Misconduct* - Publishing others’ private information
+without explicit permission - Misrepresenting affiliation or
+contributions - Plagiarism or claiming credit for others’ work -
+Retaliating against anyone who reports a Code of Conduct violation -
+Other conduct which could reasonably be considered inappropriate in a
+professional setting
+
+==== Grey Areas
+
+Some situations require judgement. When uncertain:
+
+* *Intent vs Impact*: Good intentions do not excuse harmful impact.
+Focus on making things right.
+* *Power Dynamics*: Those with more power (maintainers, employers,
+experienced contributors) must be especially mindful of their impact.
+* *Cultural Differences*: What’s acceptable varies by culture. When in
+doubt, err on the side of caution and ask.
+* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch
+up, not down.
+
+'''''
+
+=== Scope
+
+This Code of Conduct applies within all community spaces, including:
+
+*Online Spaces* - Repository discussions, issues, and pull/merge
+requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing
+lists and forums - Social media when representing the project - Video
+calls and virtual meetings
+
+*In-Person Spaces* - Conferences, meetups, and events - Workshops and
+training sessions - Any gathering where you represent the project
+
+*Representation* This Code of Conduct also applies when an individual is
+officially representing the community in public spaces. Examples
+include:
+
+* Using an official project email address
+* Posting via an official social media account
+* Acting as an appointed representative at an event
+* Speaking on behalf of the project
+
+'''''
+
+=== Enforcement
+
+==== Reporting
+
+If you experience or witness unacceptable behaviour, or have any other
+concerns, please report it as soon as possible.
+
+*How to Report*
+
+[width="99%",cols="30%,33%,37%",options="header",]
+|===
+|Method |Details |Best For
+|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters
+
+|*Private Message* |Contact any maintainer directly |Quick questions,
+minor issues
+
+|*Anonymous Form* |[Link to form if available] |When you need anonymity
+|===
+
+*What to Include*
+
+* Your contact information (unless anonymous)
+* Names/usernames of those involved
+* Description of what happened
+* When and where it occurred
+* Any witnesses
+* Any supporting evidence (screenshots, links)
+* How you would like us to respond (if you have a preference)
+
+*What Happens Next*
+
+[arabic]
+. You will receive acknowledgment within *48 hours*
+. The Code of Conduct Committee will review the report
+. We may ask for additional information
+. We will determine appropriate action
+. We will inform you of the outcome (respecting others’ privacy)
+
+==== Confidentiality
+
+All reports will be handled with discretion:
+
+* Reporter identity is protected by default
+* Details are shared only with those who need to know
+* We will ask before naming you in any communication
+* Anonymous reports are accepted and investigated
+
+==== Conflicts of Interest
+
+If a Code of Conduct Committee member is involved in an incident:
+
+* They will recuse themselves from the process
+* Another maintainer or external party will handle the report
+* We will disclose any potential conflicts
+
+'''''
+
+=== Enforcement Guidelines
+
+The Code of Conduct Committee will follow these guidelines in
+determining consequences:
+
+==== 1. Correction
+
+*Community Impact*: Use of inappropriate language or other behaviour
+deemed unprofessional or unwelcome.
+
+*Consequence*: A private, written warning providing clarity around the
+nature of the violation and an explanation of why the behaviour was
+inappropriate. A public apology may be requested.
+
+*Duration*: Immediate
+
+==== 2. Warning
+
+*Community Impact*: A violation through a single incident or series of
+actions.
+
+*Consequence*: A warning with consequences for continued behaviour. No
+interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, for a specified period. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+*Duration*: 1-4 weeks
+
+==== 3. Temporary Ban
+
+*Community Impact*: A serious violation of community standards,
+including sustained inappropriate behaviour.
+
+*Consequence*: A temporary ban from any sort of interaction or public
+communication with the community for a specified period. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during
+this period. Violating these terms may lead to a permanent ban.
+
+*Duration*: 1-6 months
+
+==== 4. Permanent Ban
+
+*Community Impact*: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behaviour, harassment of an
+individual, or aggression toward or disparagement of classes of
+individuals.
+
+*Consequence*: A permanent ban from any sort of public interaction
+within the community.
+
+*Duration*: Permanent (with appeal rights after 12 months)
+
+==== Enforcement Across Perimeters
+
+For contributors with elevated access (Perimeter 2 or 1):
+
+[cols=",",options="header",]
+|===
+|Level |Additional Consequence
+|Correction |Noted in contributor record
+|Warning |Access privileges may be temporarily reduced
+|Temporary Ban |Access reduced to Perimeter 3 for ban duration
+|Permanent Ban |All access revoked
+|===
+
+'''''
+
+=== Appeals
+
+If you believe an enforcement decision was made in error:
+
+[arabic]
+. *Wait 7 days* after the decision (cooling-off period)
+. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original
+Report ID]`"
+. *Explain* why you believe the decision should be reconsidered
+. *Provide* any new information not previously available
+
+*Appeals Process*
+
+* Appeals are reviewed by a different Code of Conduct Committee member
+than the original
+* You will receive a response within 14 days
+* The appeals decision is final
+* You may only appeal once per incident
+
+*Grounds for Appeal*
+
+* Procedural errors in the original investigation
+* New evidence not previously available
+* Disproportionate response to the violation
+* Misunderstanding of facts
+
+'''''
+
+=== Supporting Those Who Report
+
+We are committed to supporting those who report violations:
+
+*We Will* - Believe and take all reports seriously - Respect your
+privacy and confidentiality preferences - Keep you informed of progress
+(if you wish) - Take steps to protect you from retaliation - Provide
+resources if you need support
+
+*We Will Not* - Require you to confront the person directly - Dismiss
+reports without investigation - Reveal your identity without consent -
+Tolerate retaliation against reporters - Rush you to make decisions
+
+'''''
+
+=== Prevention
+
+Beyond enforcement, we actively work to prevent issues:
+
+*Onboarding* - All contributors are expected to read this Code of
+Conduct - Perimeter 2 applicants must confirm they’ve read and
+understood it - Maintainers receive additional training on enforcement
+
+*Culture* - We model the behaviour we expect - We intervene early when
+we see potential issues - We thank people for positive contributions -
+We create opportunities for diverse voices
+
+*Review* - This Code of Conduct is reviewed annually - Community
+feedback is welcomed - Changes are communicated clearly
+
+'''''
+
+=== Acknowledgments
+
+This Code of Conduct is adapted from:
+
+* https://www.contributor-covenant.org/[Contributor Covenant], version
+2.1
+* https://www.djangoproject.com/conduct/[Django Code of Conduct]
+* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of
+Conduct]
+* https://www.python.org/psf/conduct/[Python Community Code of Conduct]
+
+We thank these communities for their leadership in creating welcoming
+spaces.
+
+'''''
+
+=== Questions?
+
+If you have questions about this Code of Conduct:
+
+* Open a
+https://github.com/hyperpolymath/wokelang/discussions[Discussion] (for
+general questions)
+* Email j.d.a.jewell@open.ac.uk (for private questions)
+* Contact any maintainer directly
+
+'''''
+
+=== Summary
+
+*Be kind. Be respectful. Be collaborative.*
+
+We’re all here because we care about this project. Let’s make it a place
+where everyone can do their best work.
+
+'''''
+
+Last updated: 2026 · Based on Contributor Covenant 2.1
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index 54f7d80..0000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,312 +0,0 @@
-
-# Code of Conduct
-
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in wokelang a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
-We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation.
-
----
-
-## Our Standards
-
-### Expected Behaviour
-
-The following behaviours contribute to a positive environment:
-
-**Communication**
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Giving and gracefully accepting constructive feedback
-- Assuming good intent while addressing impact
-- Communicating clearly and patiently, especially with newcomers
-
-**Collaboration**
-- Focusing on what is best for the community
-- Showing empathy and kindness toward other community members
-- Being collaborative rather than competitive
-- Mentoring and supporting less experienced contributors
-- Celebrating others' contributions and successes
-
-**Professionalism**
-- Accepting responsibility and apologising to those affected by our mistakes
-- Learning from the experience and avoiding repetition
-- Respecting others' time and attention
-- Staying on topic in project spaces
-- Following project guidelines and conventions
-
-**Accessibility**
-- Using plain language and avoiding unnecessary jargon
-- Providing alt text for images and transcripts for audio/video
-- Being patient with those using assistive technologies
-- Accommodating different communication styles and needs
-- Recognising that not everyone communicates the same way
-
-### Unacceptable Behaviour
-
-The following behaviours are considered harassment and are unacceptable:
-
-**Harassment**
-- The use of sexualised language or imagery, and sexual attention or advances of any kind
-- Trolling, insulting or derogatory comments, and personal or political attacks
-- Public or private harassment
-- Deliberate intimidation, stalking, or following (online or in-person)
-- Unwelcome physical contact or simulated physical contact (e.g., emoji)
-- Sustained disruption of talks, events, or online discussions
-
-**Discrimination**
-- Discriminatory jokes and language
-- Posting or threatening to post others' personally identifying information ("doxing")
-- Advocating for, or encouraging, any of the above behaviour
-- Microaggressions — subtle, often unintentional, discriminatory comments or actions
-
-**Professional Misconduct**
-- Publishing others' private information without explicit permission
-- Misrepresenting affiliation or contributions
-- Plagiarism or claiming credit for others' work
-- Retaliating against anyone who reports a Code of Conduct violation
-- Other conduct which could reasonably be considered inappropriate in a professional setting
-
-### Grey Areas
-
-Some situations require judgement. When uncertain:
-
-- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right.
-- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact.
-- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask.
-- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down.
-
----
-
-## Scope
-
-This Code of Conduct applies within all community spaces, including:
-
-**Online Spaces**
-- Repository discussions, issues, and pull/merge requests
-- Project chat channels (Matrix, Discord, Slack, IRC)
-- Mailing lists and forums
-- Social media when representing the project
-- Video calls and virtual meetings
-
-**In-Person Spaces**
-- Conferences, meetups, and events
-- Workshops and training sessions
-- Any gathering where you represent the project
-
-**Representation**
-This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include:
-
-- Using an official project email address
-- Posting via an official social media account
-- Acting as an appointed representative at an event
-- Speaking on behalf of the project
-
----
-
-## Enforcement
-
-### Reporting
-
-If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible.
-
-**How to Report**
-
-| Method | Details | Best For |
-|--------|---------|----------|
-| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters |
-| **Private Message** | Contact any maintainer directly | Quick questions, minor issues |
-| **Anonymous Form** | [Link to form if available] | When you need anonymity |
-
-**What to Include**
-
-- Your contact information (unless anonymous)
-- Names/usernames of those involved
-- Description of what happened
-- When and where it occurred
-- Any witnesses
-- Any supporting evidence (screenshots, links)
-- How you would like us to respond (if you have a preference)
-
-**What Happens Next**
-
-1. You will receive acknowledgment within **48 hours**
-2. The Code of Conduct Committee will review the report
-3. We may ask for additional information
-4. We will determine appropriate action
-5. We will inform you of the outcome (respecting others' privacy)
-
-### Confidentiality
-
-All reports will be handled with discretion:
-
-- Reporter identity is protected by default
-- Details are shared only with those who need to know
-- We will ask before naming you in any communication
-- Anonymous reports are accepted and investigated
-
-### Conflicts of Interest
-
-If a Code of Conduct Committee member is involved in an incident:
-
-- They will recuse themselves from the process
-- Another maintainer or external party will handle the report
-- We will disclose any potential conflicts
-
----
-
-## Enforcement Guidelines
-
-The Code of Conduct Committee will follow these guidelines in determining consequences:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome.
-
-**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested.
-
-**Duration**: Immediate
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-**Duration**: 1-4 weeks
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-**Duration**: 1-6 months
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the community.
-
-**Duration**: Permanent (with appeal rights after 12 months)
-
-### Enforcement Across Perimeters
-
-For contributors with elevated access (Perimeter 2 or 1):
-
-| Level | Additional Consequence |
-|-------|----------------------|
-| Correction | Noted in contributor record |
-| Warning | Access privileges may be temporarily reduced |
-| Temporary Ban | Access reduced to Perimeter 3 for ban duration |
-| Permanent Ban | All access revoked |
-
----
-
-## Appeals
-
-If you believe an enforcement decision was made in error:
-
-1. **Wait 7 days** after the decision (cooling-off period)
-2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]"
-3. **Explain** why you believe the decision should be reconsidered
-4. **Provide** any new information not previously available
-
-**Appeals Process**
-
-- Appeals are reviewed by a different Code of Conduct Committee member than the original
-- You will receive a response within 14 days
-- The appeals decision is final
-- You may only appeal once per incident
-
-**Grounds for Appeal**
-
-- Procedural errors in the original investigation
-- New evidence not previously available
-- Disproportionate response to the violation
-- Misunderstanding of facts
-
----
-
-## Supporting Those Who Report
-
-We are committed to supporting those who report violations:
-
-**We Will**
-- Believe and take all reports seriously
-- Respect your privacy and confidentiality preferences
-- Keep you informed of progress (if you wish)
-- Take steps to protect you from retaliation
-- Provide resources if you need support
-
-**We Will Not**
-- Require you to confront the person directly
-- Dismiss reports without investigation
-- Reveal your identity without consent
-- Tolerate retaliation against reporters
-- Rush you to make decisions
-
----
-
-## Prevention
-
-Beyond enforcement, we actively work to prevent issues:
-
-**Onboarding**
-- All contributors are expected to read this Code of Conduct
-- Perimeter 2 applicants must confirm they've read and understood it
-- Maintainers receive additional training on enforcement
-
-**Culture**
-- We model the behaviour we expect
-- We intervene early when we see potential issues
-- We thank people for positive contributions
-- We create opportunities for diverse voices
-
-**Review**
-- This Code of Conduct is reviewed annually
-- Community feedback is welcomed
-- Changes are communicated clearly
-
----
-
-## Acknowledgments
-
-This Code of Conduct is adapted from:
-
-- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1
-- [Django Code of Conduct](https://www.djangoproject.com/conduct/)
-- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct)
-- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)
-
-We thank these communities for their leadership in creating welcoming spaces.
-
----
-
-## Questions?
-
-If you have questions about this Code of Conduct:
-
-- Open a [Discussion](https://github.com/hyperpolymath/wokelang/discussions) (for general questions)
-- Email j.d.a.jewell@open.ac.uk (for private questions)
-- Contact any maintainer directly
-
----
-
-## Summary
-
-**Be kind. Be respectful. Be collaborative.**
-
-We're all here because we care about this project. Let's make it a place where everyone can do their best work.
-
----
-
-Last updated: 2026 · Based on Contributor Covenant 2.1
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 5c52d00..0ce4f90 100644
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -1,22 +1,27 @@
-// SPDX-License-Identifier: CC-BY-SA-4.0
-// Copyright (c) Jonathan D.A. Jewell
-
-= Contributing Guide
+== Contributing to WokeLang
-== Getting Started
+Thank you for your interest in contributing.
-1. Fork the repository
-2. Create a feature branch from `main`
-3. Sign off commits (`git commit -s`)
-4. Submit a pull request
+=== Getting Started
-== Commit Guidelines
+[arabic]
+. Fork the repository
+. Create a feature branch (`+feat/my-feature+`)
+. Ensure SPDX headers on all new files (`+MPL-2.0+`)
+. Run `+panic-attack assail+` before committing
+. Submit a pull request
-* Conventional commits: `type(scope): description`
-* Sign all commits (DCO required)
-* Atomic, focused commits
+=== Code Quality
-== License
+* All code must have detailed annotations
+* No dangerous patterns: `+believe_me+`, `+assert_total+`, `+sorry+`,
+`+Admitted+`, `+unsafeCoerce+`, `+Obj.magic+`
+* Tests required for new functionality
-Contributions licensed under project license.
+=== Reporting Issues
+Use GitHub Issues with clear reproduction steps.
+
+=== Author
+
+Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index 8c492f2..0000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,29 +0,0 @@
-
-# Contributing to WokeLang
-
-Thank you for your interest in contributing.
-
-## Getting Started
-
-1. Fork the repository
-2. Create a feature branch (`feat/my-feature`)
-3. Ensure SPDX headers on all new files (`MPL-2.0`)
-4. Run `panic-attack assail` before committing
-5. Submit a pull request
-
-## Code Quality
-
-- All code must have detailed annotations
-- No dangerous patterns: `believe_me`, `assert_total`, `sorry`, `Admitted`, `unsafeCoerce`, `Obj.magic`
-- Tests required for new functionality
-
-## Reporting Issues
-
-Use GitHub Issues with clear reproduction steps.
-
-## Author
-
-Jonathan D.A. Jewell
diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc
index e41020d..9b836fb 100644
--- a/GOVERNANCE.adoc
+++ b/GOVERNANCE.adoc
@@ -1,162 +1,60 @@
-// SPDX-License-Identifier: CC-BY-SA-4.0
-// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
-= Governance Model
-:toc: preamble
+== Governance
-This document describes the governance model for this repository.
+=== Overview
-== Overview
+This project is governed by the following principles and structures to
+ensure transparent, inclusive, and effective decision-making.
-This repository follows a **Sole Maintainer Governance Model**:
+=== Roles and Responsibilities
-* Single maintainer (@hyperpolymath) has full authority over the project
-* All contributions are welcome and reviewed by the maintainer
-* Decisions are made transparently through GitHub issues and discussions
-* The project adheres to the hyperpolymath estate policies where applicable
+==== Maintainers
-== Core Principles
+Maintainers are responsible for: - Reviewing and merging pull requests -
+Managing releases and versioning - Ensuring code quality and standards -
+Triaging issues and bug reports - Community engagement and support
-[cols="1,2"]
-|===
-| Principle | Description
+==== Contributors
-| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input
+Contributors are expected to: - Follow the code of conduct - Submit
+well-documented pull requests - Write tests for new functionality -
+Maintain existing tests - Update documentation as needed
-| **Meritocracy** | Contributions are judged on technical merit, not contributor identity
+=== Decision Making
-| **Transparency** | All significant decisions are documented publicly
+==== Minor Changes
-| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary
+* Can be made by any maintainer
+* Include bug fixes, documentation updates, dependency updates
-| **Open Contribution** | Anyone can contribute via fork and pull request
+==== Major Changes
-|===
+* Require discussion in issues or pull requests
+* Include new features, architectural changes, API changes
+* Need approval from at least 2 maintainers
-== Roles and Permissions
+==== Breaking Changes
-[cols="1,2,2"]
-|===
-| Role | Permissions | Assignment
+* Require RFC (Request for Comments) process
+* Need approval from majority of maintainers
+* Must include migration guide
-| **Maintainer** | Write access, merge rights, admin | @hyperpolymath
-| **Contributors** | Read access, fork, submit PRs | All GitHub users
-| **Users** | Use the software, report issues | All GitHub users
+=== Code of Conduct
-|===
+All participants are expected to follow our Code of Conduct. Violations
+can be reported to the maintainers.
-== Decision Making Framework
+=== Communication
-=== Routine Decisions
+* *Issues*: For bug reports and feature requests
+* *Discussions*: For questions and general discussion
+* *Pull Requests*: For code contributions
-* Bug fixes
-* Documentation improvements
-* Minor feature additions
-* Dependency updates
+=== Licensing
-**Process**: Maintainer reviews and merges PRs that meet quality standards.
+All contributions are made under the terms of the repository’s LICENSE
+file. By submitting a pull request, you agree to license your
+contributions accordingly.
-=== Significant Changes
+'''''
-* New major features
-* API changes
-* Architecture modifications
-* Breaking changes
-
-**Process**:
-. Open issue describing the change
-. Discuss with community (minimum 72 hours)
-. Maintainer makes final decision
-. Document rationale in issue/PR
-
-=== Structural Decisions
-
-* Repository purpose/renaming
-* License changes
-* Ownership transfer
-* Deprecation/archival
-
-**Process**:
-. Extended discussion (minimum 1 week)
-. Maintainer makes final decision
-. Document in CHANGELOG and governance docs
-
-== Contribution Lifecycle
-
-[cols="1,2"]
-|===
-| Stage | Process
-
-| **Ideation** | Open issue, discuss feasibility
-
-| **Development** | Fork, implement, test thoroughly
-
-| **Review** | Submit PR, maintainer reviews within 7 days
-
-| **Merge** | Maintainer merges or requests changes
-
-| **Release** | Maintainer publishes according to project conventions
-
-|===
-
-== Conflict Resolution
-
-In case of disagreements:
-
-. Discuss in the relevant GitHub issue or PR
-. Provide technical justification for positions
-. Maintainer mediates and makes final decision
-. Decision is documented and can be revisited later
-
-== Project Policies
-
-This repository adheres to hyperpolymath estate-wide policies:
-
-* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc)
-* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md
-* **Security**: Follows hyperpolymath SECURITY.md
-* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions
-
-== Repository-Specific Conventions
-
-[cols="1,2"]
-|===
-| Convention | Description
-
-| **Signing** | All commits must be signed (SSH or GPG)
-
-| **SPDX Headers** | All source files must have SPDX license identifiers
-
-| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root
-
-| **Machine Readable** | META.a2ml in .machine_readable/6a2/
-
-| **CI/CD** | GitHub Actions workflows in .github/workflows/
-
-|===
-
-== Governance Evolution
-
-As the project grows, this governance model may evolve:
-
-* **Adding Co-Maintainers**: When contribution volume warrants it
-* **Forming a Team**: For complex multi-maintainer projects
-* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories)
-
-Changes to this document require the same process as Significant Changes above.
-
-== See Also
-
-* link:MAINTAINERS.adoc[Maintainers]
-* link:CODE_OF_CONDUCT.md[Code of Conduct]
-* link:CONTRIBUTING.adoc[Contributing Guide]
-* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy]
-* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)]
-
-== Changelog
-
-[cols="1,1,1"]
-|===
-| Date | Change | By
-
-| 2026-06-07 | Initial governance model established | @hyperpolymath
-|===
+_Last updated: 2026-07-18_
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
deleted file mode 100644
index e27364c..0000000
--- a/GOVERNANCE.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Governance
-
-## Overview
-
-This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making.
-
-## Roles and Responsibilities
-
-### Maintainers
-
-Maintainers are responsible for:
-- Reviewing and merging pull requests
-- Managing releases and versioning
-- Ensuring code quality and standards
-- Triaging issues and bug reports
-- Community engagement and support
-
-### Contributors
-
-Contributors are expected to:
-- Follow the code of conduct
-- Submit well-documented pull requests
-- Write tests for new functionality
-- Maintain existing tests
-- Update documentation as needed
-
-## Decision Making
-
-### Minor Changes
-- Can be made by any maintainer
-- Include bug fixes, documentation updates, dependency updates
-
-### Major Changes
-- Require discussion in issues or pull requests
-- Include new features, architectural changes, API changes
-- Need approval from at least 2 maintainers
-
-### Breaking Changes
-- Require RFC (Request for Comments) process
-- Need approval from majority of maintainers
-- Must include migration guide
-
-## Code of Conduct
-
-All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers.
-
-## Communication
-
-- **Issues**: For bug reports and feature requests
-- **Discussions**: For questions and general discussion
-- **Pull Requests**: For code contributions
-
-## Licensing
-
-All contributions are made under the terms of the repository's LICENSE file.
-By submitting a pull request, you agree to license your contributions accordingly.
-
----
-
-*Last updated: 2026-07-18*
diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc
index 4bef84b..59ca2fd 100644
--- a/MAINTAINERS.adoc
+++ b/MAINTAINERS.adoc
@@ -1,20 +1,19 @@
-// SPDX-License-Identifier: CC-BY-SA-4.0
-// Copyright (c) Jonathan D.A. Jewell
-
-= Maintainers
-:toc: preamble
+// SPDX-License-Identifier: CC-BY-SA-4.0 = Maintainers :toc: preamble
-This document lists the maintainers of this project and their responsibilities.
+This document lists the maintainers of this project and their
+responsibilities.
== Current Maintainers
-[cols="2,3,2",options="header"]
-|===
-| Name | Role | Contact
+[cols="`2,3,2`",options="`header`"] |=== | Name | Role | Contact
+
+[verse]
+--
+Jonathan D.A. Jewell
+Lead Maintainer
+https://github.com/hyperpolymath[@hyperpolymath]
+--
-| Jonathan D.A. Jewell
-| Lead Maintainer
-| https://github.com/hyperpolymath[@hyperpolymath]
|===
== Responsibilities
@@ -25,25 +24,29 @@ Maintainers are responsible for:
* Triaging issues and feature requests
* Ensuring code quality and security standards
* Managing releases and versioning
-* Upholding the project's code of conduct
+* Upholding the project’s code of conduct
== Becoming a Maintainer
Contributors who demonstrate:
* Consistent, high-quality contributions
-* Understanding of the project's goals and standards
+* Understanding of the project’s goals and standards
* Constructive participation in discussions
-* Commitment to the project's long-term health
+* Commitment to the project’s long-term health
-May be invited to become maintainers at the discretion of existing maintainers.
+May be invited to become maintainers at the discretion of existing
+maintainers.
== Decision Making
-* Routine decisions (bug fixes, minor improvements) can be made by any maintainer
+* Routine decisions (bug fixes, minor improvements) can be made by any
+maintainer
* Significant changes require discussion and consensus among maintainers
-* Breaking changes or major features should be discussed in issues before implementation
+* Breaking changes or major features should be discussed in issues
+before implementation
== Contact
-For questions about project governance, open an issue or contact the maintainers listed above.
+For questions about project governance, open an issue or contact the
+maintainers listed above.
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
deleted file mode 100644
index ab5b55b..0000000
--- a/MAINTAINERS.md
+++ /dev/null
@@ -1,51 +0,0 @@
-
-// SPDX-License-Identifier: CC-BY-SA-4.0
-= Maintainers
-:toc: preamble
-
-This document lists the maintainers of this project and their responsibilities.
-
-== Current Maintainers
-
-[cols="2,3,2",options="header"]
-|===
-| Name | Role | Contact
-
-| Jonathan D.A. Jewell
-| Lead Maintainer
-| https://github.com/hyperpolymath[@hyperpolymath]
-|===
-
-== Responsibilities
-
-Maintainers are responsible for:
-
-* Reviewing and merging pull requests
-* Triaging issues and feature requests
-* Ensuring code quality and security standards
-* Managing releases and versioning
-* Upholding the project's code of conduct
-
-== Becoming a Maintainer
-
-Contributors who demonstrate:
-
-* Consistent, high-quality contributions
-* Understanding of the project's goals and standards
-* Constructive participation in discussions
-* Commitment to the project's long-term health
-
-May be invited to become maintainers at the discretion of existing maintainers.
-
-== Decision Making
-
-* Routine decisions (bug fixes, minor improvements) can be made by any maintainer
-* Significant changes require discussion and consensus among maintainers
-* Breaking changes or major features should be discussed in issues before implementation
-
-== Contact
-
-For questions about project governance, open an issue or contact the maintainers listed above.
diff --git a/PHRONESIS-ALIGNMENT-GAP.adoc b/PHRONESIS-ALIGNMENT-GAP.adoc
new file mode 100644
index 0000000..f3cf8c9
--- /dev/null
+++ b/PHRONESIS-ALIGNMENT-GAP.adoc
@@ -0,0 +1,432 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026
+Jonathan D.A. Jewell
+
+== Phronesis Toolchain Alignment Gap Analysis
+
+*Date:* 2026-02-01 *Status:* WokeLang catching up to Phronesis toolchain
+maturity
+
+=== Executive Summary
+
+*Phronesis:* 100% complete toolchain (production-ready) *WokeLang:* 85%
+complete core language, toolchain needs development
+
+This document tracks what WokeLang needs to implement to match
+Phronesis’s toolchain maturity.
+
+'''''
+
+=== Toolchain Comparison Matrix
+
+[width="100%",cols="25%,23%,21%,10%,21%",options="header",]
+|===
+|Component |Phronesis |WokeLang |Gap |Priority
+|*Core Language* |✅ Complete |✅ Complete |None |N/A
+|*Parser & Lexer* |✅ Complete |✅ Complete |None |N/A
+|*Type System* |✅ Complete |✅ Complete (H-M) |None |N/A
+|*Interpreter* |✅ Complete |✅ Complete |None |N/A
+|*Bytecode VM* |✅ Complete |✅ Complete |None |N/A
+|*REPL* |✅ Complete |✅ Complete |None |N/A
+|*CLI* |✅ Complete |✅ Complete |None |N/A
+|*LSP Server* |✅ Complete |❌ Missing |*MAJOR* |*P1*
+|*Debugger* |✅ Complete |❌ Missing |*MAJOR* |*P1*
+|*Testing Framework* |✅ Complete |⚠️ Partial |*MAJOR* |*P1*
+|*Profiler* |✅ Complete |❌ Missing |*MAJOR* |*P2*
+|*Doc Generator* |✅ Complete |❌ Missing |*MAJOR* |*P2*
+|*Static Analyzer* |✅ Complete |⚠️ Partial |*MEDIUM* |P3
+|*Syntax Highlighting* |✅ Complete |⚠️ Partial |*MEDIUM* |P3
+|*Error Reporter* |✅ Complete |⚠️ Partial |*MEDIUM* |P3
+|*Package Manager* |✅ Complete |❌ Missing |*MEDIUM* |P4
+|*VSCode Extension* |✅ Complete |❌ Missing |*MEDIUM* |P4
+|===
+
+'''''
+
+=== Detailed Gap Analysis
+
+==== 1. LSP Server ❌ → ✅
+
+*Phronesis has:* - Full JSON-RPC 2.0 implementation -
+textDocument/completion (auto-complete) - textDocument/hover
+(documentation) - textDocument/definition (go-to-definition) -
+textDocument/diagnostics (real-time errors) - VSCode extension
+integration
+
+*WokeLang needs:* - Implement LSP server from scratch - JSON-RPC message
+handling - Document synchronization - Symbol resolution - Diagnostic
+reporting - Language features (completion, hover, etc.)
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/lsp/server.rs
+pub struct LspServer {
+ documents: HashMap,
+ symbols: SymbolTable,
+}
+
+impl LspServer {
+ pub fn handle_completion(&self, params: CompletionParams) -> CompletionList { /* ... */ }
+ pub fn handle_hover(&self, params: HoverParams) -> Option { /* ... */ }
+ pub fn handle_definition(&self, params: DefinitionParams) -> Vec { /* ... */ }
+}
+----
+
+*Estimated Effort:* 2-3 weeks *Dependencies:* None (can start
+immediately)
+
+'''''
+
+==== 2. Debugger ❌ → ✅
+
+*Phronesis has:* - Interactive debugger REPL - Breakpoint support - Step
+execution (step, next, continue) - State inspection - Watch expressions
+- Call stack viewing
+
+*WokeLang needs:* - Debugger infrastructure - AST instrumentation for
+breakpoints - Step-through interpreter mode - Debug REPL - Variable
+inspection commands
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/debugger.rs
+pub struct Debugger {
+ breakpoints: Vec,
+ watches: Vec,
+ call_stack: Vec,
+ mode: DebugMode, // Running, Paused, Stepping
+}
+
+impl Debugger {
+ pub fn add_breakpoint(&mut self, location: SourceLocation) { /* ... */ }
+ pub fn step(&mut self) { /* ... */ }
+ pub fn inspect(&self, var_name: &str) -> Option { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1-2 weeks *Dependencies:* None
+
+'''''
+
+==== 3. Testing Framework ⚠️ → ✅
+
+*Phronesis has:* - TEST/SCENARIO/GIVEN/EXPECT DSL - Test runner
+(`+phronesis test+`) - Test discovery - Assertion framework - Test
+reporting
+
+*WokeLang has:* - Examples that serve as tests - Basic integration
+testing via examples
+
+*WokeLang needs:* - Formal test DSL or syntax - Test runner
+infrastructure - Assertion functions - Test discovery - Coverage
+reporting
+
+*Implementation Path:*
+
+[source,wokelang]
+----
+# test/consent_test.woke
+test "consent system blocks without permission" {
+ #care on;
+
+ remember result = only if okay "file.read" {
+ readFile("test.txt")
+ };
+
+ expect result to be Oops("Permission denied");
+}
+----
+
+[source,rust]
+----
+// src/test_framework.rs
+pub struct TestRunner {
+ tests: Vec,
+}
+
+impl TestRunner {
+ pub fn discover_tests(&mut self, path: &Path) { /* ... */ }
+ pub fn run_all(&self) -> TestReport { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1 week *Dependencies:* None
+
+'''''
+
+==== 4. Profiler ❌ → ✅
+
+*Phronesis has:* - Performance profiling (`+phronesis profile+`) -
+Timing measurements per function - Memory allocation tracking -
+HTML/CSV/Markdown reports - Flame graph generation
+
+*WokeLang needs:* - Profiler infrastructure - Instrumentation hooks -
+Timing collection - Report generation
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/profiler.rs
+pub struct Profiler {
+ samples: Vec,
+ start_time: Instant,
+}
+
+impl Profiler {
+ pub fn start_function(&mut self, name: &str) { /* ... */ }
+ pub fn end_function(&mut self, name: &str) { /* ... */ }
+ pub fn generate_report(&self, format: ReportFormat) -> String { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1 week *Dependencies:* None
+
+'''''
+
+==== 5. Documentation Generator ❌ → ✅
+
+*Phronesis has:* - Doc comment extraction - HTML/Markdown export - API
+reference generation - Example code inclusion - Cross-referencing
+
+*WokeLang needs:* - Doc comment parser - Documentation AST - Template
+system - Multi-format export
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/doc.rs
+pub struct DocGenerator {
+ docs: Vec,
+}
+
+impl DocGenerator {
+ pub fn extract_docs(&mut self, ast: &AST) { /* ... */ }
+ pub fn generate_html(&self) -> String { /* ... */ }
+ pub fn generate_markdown(&self) -> String { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1 week *Dependencies:* None
+
+'''''
+
+==== 6. VSCode Extension ❌ → ✅
+
+*Phronesis has:* - Full VSCode extension - Syntax highlighting - LSP
+client integration - Debugger integration - Custom commands
+
+*WokeLang needs:* - VSCode extension scaffold - TextMate grammar (syntax
+highlighting) - LSP client configuration - Extension marketplace
+publishing
+
+*Implementation Path:*
+
+....
+editors/
+└── vscode/
+ ├── package.json
+ ├── syntaxes/
+ │ └── wokelang.tmLanguage.json
+ ├── language-configuration.json
+ └── extension.js
+....
+
+*Estimated Effort:* 3-4 days (after LSP is ready) *Dependencies:* LSP
+server must be complete
+
+'''''
+
+==== 7. Static Analyzer ⚠️ → ✅
+
+*Phronesis has:* - Dead code detection - Unreachable code detection -
+Security vulnerability scanning - Code quality metrics - Comprehensive
+checks
+
+*WokeLang has:* - Basic linter (`+woke lint+`) - Some static checks
+
+*WokeLang needs:* - Advanced analysis passes - Data flow analysis -
+Control flow analysis - Security checks specific to consent system -
+Capability leak detection
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/analyzer.rs
+pub struct StaticAnalyzer {
+ checks: Vec,
+}
+
+impl StaticAnalyzer {
+ pub fn analyze(&self, ast: &AST) -> Vec { /* ... */ }
+}
+
+pub struct DeadCodePass;
+impl AnalysisPass for DeadCodePass {
+ fn run(&self, ast: &AST) -> Vec { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1-2 weeks *Dependencies:* None
+
+'''''
+
+==== 8. Syntax Highlighting ⚠️ → ✅
+
+*Phronesis has:* - VSCode/VSCodium - Vim/Neovim - Emacs - Sublime Text -
+Kate/KWrite - GitHub Linguist
+
+*WokeLang has:* - Partial GitHub detection (.gitattributes)
+
+*WokeLang needs:* - Complete TextMate grammar - Vim syntax file - Emacs
+major mode - Sublime syntax - Kate XML syntax - GitHub Linguist
+registration
+
+*Implementation Path:*
+
+....
+syntax/
+├── wokelang.tmLanguage.json # VSCode/Sublime/GitHub
+├── wokelang.vim # Vim/Neovim
+├── wokelang-mode.el # Emacs
+└── wokelang.xml # Kate
+....
+
+*Estimated Effort:* 2-3 days *Dependencies:* None (can do immediately)
+
+'''''
+
+==== 9. Error Reporter ⚠️ → ✅
+
+*Phronesis has:* - Colorized error messages - Source context with line
+numbers - Error suggestions ("`did you mean…`") - Error codes (E0001,
+E0002, etc.) - Related information - Help text
+
+*WokeLang has:* - Basic error messages - Miette integration (partial)
+
+*WokeLang needs:* - Comprehensive error catalog - Suggestion engine -
+Better formatting - Error code system
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/diagnostics.rs
+pub struct Diagnostic {
+ code: ErrorCode,
+ message: String,
+ location: SourceLocation,
+ suggestions: Vec,
+ help: Option,
+}
+
+impl Diagnostic {
+ pub fn format_fancy(&self) -> String { /* ... */ }
+}
+----
+
+*Estimated Effort:* 1 week *Dependencies:* None
+
+'''''
+
+==== 10. Package Manager ❌ → ✅
+
+*Phronesis has:* - `+phronesis pkg+` command - Package registry client -
+Dependency resolution - Version management - Package publishing
+
+*WokeLang needs:* - Package manifest format (wokelang.ncl) - Dependency
+resolver - Package registry client - Version constraint solver - Lock
+file format
+
+*Implementation Path:*
+
+[source,rust]
+----
+// src/pkg/manager.rs
+pub struct PackageManager {
+ registry: RegistryClient,
+ cache: PackageCache,
+}
+
+impl PackageManager {
+ pub fn install(&self, name: &str, version: &str) -> Result<()> { /* ... */ }
+ pub fn resolve_deps(&self, manifest: &Manifest) -> DependencyGraph { /* ... */ }
+}
+----
+
+*Estimated Effort:* 2-3 weeks *Dependencies:* None (but needs registry
+service eventually)
+
+'''''
+
+=== Implementation Roadmap
+
+==== Phase 1: Quick Wins (1 week)
+
+*Goal:* Close easy gaps 1. ✅ Create TOOLCHAIN-WISHLIST.md (complete) 2.
+✅ Align Justfile structure (complete) 3. Create syntax highlighting
+files 4. Enhanced error messages
+
+==== Phase 2: Testing & Quality (1-2 weeks)
+
+*Goal:* Production readiness 1. Testing framework 2. Static analyzer
+enhancements 3. Comprehensive test suite 4. Error reporter improvements
+
+==== Phase 3: Developer Tools (6-8 weeks)
+
+*Goal:* IDE experience 1. LSP server (3 weeks) 2. Debugger (2 weeks) 3.
+VSCode extension (1 week) 4. Profiler (1 week) 5. Doc generator (1 week)
+
+==== Phase 4: Ecosystem (2-3 weeks)
+
+*Goal:* Package ecosystem 1. Package manager (2 weeks) 2. Package
+registry (when ready)
+
+'''''
+
+=== Priority Recommendations
+
+*P1 (Start Immediately):* - Syntax highlighting (quick win, 2-3 days) -
+Testing framework (essential, 1 week)
+
+*P2 (Next Month):* - LSP server (game changer, 2-3 weeks) - Debugger
+(essential dev tool, 1-2 weeks)
+
+*P3 (Next Quarter):* - Profiler (performance, 1 week) - Doc generator
+(onboarding, 1 week) - Static analyzer (quality, 1-2 weeks)
+
+*P4 (As Needed):* - Package manager (ecosystem growth, 2-3 weeks) -
+VSCode extension (after LSP, 3-4 days)
+
+'''''
+
+=== Success Metrics
+
+*Toolchain Parity Achieved When:* - ✅ LSP server operational - ✅
+Debugger with breakpoints working - ✅ Testing framework running test
+suites - ✅ Profiler generating reports - ✅ Docs auto-generated from
+code - ✅ VSCode extension published - ✅ Package manager functional
+
+*Timeline to Parity:* 10-12 weeks (focused development)
+
+'''''
+
+=== Resources Needed
+
+*Development:* - 1 full-time developer: 10-12 weeks - OR 2 part-time
+developers: 5-6 weeks (parallelizable)
+
+*Skills Required:* - Rust programming - LSP protocol knowledge -
+Compiler/interpreter development - VSCode extension API - Package
+management systems
+
+'''''
+
+*Maintainer:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk *Date:*
+2026-02-01 *License:* MPL-2.0 *Related:* TOOLCHAIN-WISHLIST.md,
+NEXT-STEPS.adoc
diff --git a/PHRONESIS-ALIGNMENT-GAP.md b/PHRONESIS-ALIGNMENT-GAP.md
deleted file mode 100644
index c7f2f1e..0000000
--- a/PHRONESIS-ALIGNMENT-GAP.md
+++ /dev/null
@@ -1,503 +0,0 @@
-
-// SPDX-License-Identifier: CC-BY-SA-4.0
-// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
-
-# Phronesis Toolchain Alignment Gap Analysis
-**Date:** 2026-02-01
-**Status:** WokeLang catching up to Phronesis toolchain maturity
-
-## Executive Summary
-
-**Phronesis:** 100% complete toolchain (production-ready)
-**WokeLang:** 85% complete core language, toolchain needs development
-
-This document tracks what WokeLang needs to implement to match Phronesis's toolchain maturity.
-
----
-
-## Toolchain Comparison Matrix
-
-| Component | Phronesis | WokeLang | Gap | Priority |
-|-----------|-----------|----------|-----|----------|
-| **Core Language** | ✅ Complete | ✅ Complete | None | N/A |
-| **Parser & Lexer** | ✅ Complete | ✅ Complete | None | N/A |
-| **Type System** | ✅ Complete | ✅ Complete (H-M) | None | N/A |
-| **Interpreter** | ✅ Complete | ✅ Complete | None | N/A |
-| **Bytecode VM** | ✅ Complete | ✅ Complete | None | N/A |
-| **REPL** | ✅ Complete | ✅ Complete | None | N/A |
-| **CLI** | ✅ Complete | ✅ Complete | None | N/A |
-| **LSP Server** | ✅ Complete | ❌ Missing | **MAJOR** | **P1** |
-| **Debugger** | ✅ Complete | ❌ Missing | **MAJOR** | **P1** |
-| **Testing Framework** | ✅ Complete | ⚠️ Partial | **MAJOR** | **P1** |
-| **Profiler** | ✅ Complete | ❌ Missing | **MAJOR** | **P2** |
-| **Doc Generator** | ✅ Complete | ❌ Missing | **MAJOR** | **P2** |
-| **Static Analyzer** | ✅ Complete | ⚠️ Partial | **MEDIUM** | P3 |
-| **Syntax Highlighting** | ✅ Complete | ⚠️ Partial | **MEDIUM** | P3 |
-| **Error Reporter** | ✅ Complete | ⚠️ Partial | **MEDIUM** | P3 |
-| **Package Manager** | ✅ Complete | ❌ Missing | **MEDIUM** | P4 |
-| **VSCode Extension** | ✅ Complete | ❌ Missing | **MEDIUM** | P4 |
-
----
-
-## Detailed Gap Analysis
-
-### 1. LSP Server ❌ → ✅
-**Phronesis has:**
-- Full JSON-RPC 2.0 implementation
-- textDocument/completion (auto-complete)
-- textDocument/hover (documentation)
-- textDocument/definition (go-to-definition)
-- textDocument/diagnostics (real-time errors)
-- VSCode extension integration
-
-**WokeLang needs:**
-- Implement LSP server from scratch
-- JSON-RPC message handling
-- Document synchronization
-- Symbol resolution
-- Diagnostic reporting
-- Language features (completion, hover, etc.)
-
-**Implementation Path:**
-```rust
-// src/lsp/server.rs
-pub struct LspServer {
- documents: HashMap,
- symbols: SymbolTable,
-}
-
-impl LspServer {
- pub fn handle_completion(&self, params: CompletionParams) -> CompletionList { /* ... */ }
- pub fn handle_hover(&self, params: HoverParams) -> Option { /* ... */ }
- pub fn handle_definition(&self, params: DefinitionParams) -> Vec { /* ... */ }
-}
-```
-
-**Estimated Effort:** 2-3 weeks
-**Dependencies:** None (can start immediately)
-
----
-
-### 2. Debugger ❌ → ✅
-**Phronesis has:**
-- Interactive debugger REPL
-- Breakpoint support
-- Step execution (step, next, continue)
-- State inspection
-- Watch expressions
-- Call stack viewing
-
-**WokeLang needs:**
-- Debugger infrastructure
-- AST instrumentation for breakpoints
-- Step-through interpreter mode
-- Debug REPL
-- Variable inspection commands
-
-**Implementation Path:**
-```rust
-// src/debugger.rs
-pub struct Debugger {
- breakpoints: Vec,
- watches: Vec,
- call_stack: Vec,
- mode: DebugMode, // Running, Paused, Stepping
-}
-
-impl Debugger {
- pub fn add_breakpoint(&mut self, location: SourceLocation) { /* ... */ }
- pub fn step(&mut self) { /* ... */ }
- pub fn inspect(&self, var_name: &str) -> Option { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1-2 weeks
-**Dependencies:** None
-
----
-
-### 3. Testing Framework ⚠️ → ✅
-**Phronesis has:**
-- TEST/SCENARIO/GIVEN/EXPECT DSL
-- Test runner (`phronesis test`)
-- Test discovery
-- Assertion framework
-- Test reporting
-
-**WokeLang has:**
-- Examples that serve as tests
-- Basic integration testing via examples
-
-**WokeLang needs:**
-- Formal test DSL or syntax
-- Test runner infrastructure
-- Assertion functions
-- Test discovery
-- Coverage reporting
-
-**Implementation Path:**
-```wokelang
-# test/consent_test.woke
-test "consent system blocks without permission" {
- #care on;
-
- remember result = only if okay "file.read" {
- readFile("test.txt")
- };
-
- expect result to be Oops("Permission denied");
-}
-```
-
-```rust
-// src/test_framework.rs
-pub struct TestRunner {
- tests: Vec,
-}
-
-impl TestRunner {
- pub fn discover_tests(&mut self, path: &Path) { /* ... */ }
- pub fn run_all(&self) -> TestReport { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1 week
-**Dependencies:** None
-
----
-
-### 4. Profiler ❌ → ✅
-**Phronesis has:**
-- Performance profiling (`phronesis profile`)
-- Timing measurements per function
-- Memory allocation tracking
-- HTML/CSV/Markdown reports
-- Flame graph generation
-
-**WokeLang needs:**
-- Profiler infrastructure
-- Instrumentation hooks
-- Timing collection
-- Report generation
-
-**Implementation Path:**
-```rust
-// src/profiler.rs
-pub struct Profiler {
- samples: Vec,
- start_time: Instant,
-}
-
-impl Profiler {
- pub fn start_function(&mut self, name: &str) { /* ... */ }
- pub fn end_function(&mut self, name: &str) { /* ... */ }
- pub fn generate_report(&self, format: ReportFormat) -> String { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1 week
-**Dependencies:** None
-
----
-
-### 5. Documentation Generator ❌ → ✅
-**Phronesis has:**
-- Doc comment extraction
-- HTML/Markdown export
-- API reference generation
-- Example code inclusion
-- Cross-referencing
-
-**WokeLang needs:**
-- Doc comment parser
-- Documentation AST
-- Template system
-- Multi-format export
-
-**Implementation Path:**
-```rust
-// src/doc.rs
-pub struct DocGenerator {
- docs: Vec,
-}
-
-impl DocGenerator {
- pub fn extract_docs(&mut self, ast: &AST) { /* ... */ }
- pub fn generate_html(&self) -> String { /* ... */ }
- pub fn generate_markdown(&self) -> String { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1 week
-**Dependencies:** None
-
----
-
-### 6. VSCode Extension ❌ → ✅
-**Phronesis has:**
-- Full VSCode extension
-- Syntax highlighting
-- LSP client integration
-- Debugger integration
-- Custom commands
-
-**WokeLang needs:**
-- VSCode extension scaffold
-- TextMate grammar (syntax highlighting)
-- LSP client configuration
-- Extension marketplace publishing
-
-**Implementation Path:**
-```
-editors/
-└── vscode/
- ├── package.json
- ├── syntaxes/
- │ └── wokelang.tmLanguage.json
- ├── language-configuration.json
- └── extension.js
-```
-
-**Estimated Effort:** 3-4 days (after LSP is ready)
-**Dependencies:** LSP server must be complete
-
----
-
-### 7. Static Analyzer ⚠️ → ✅
-**Phronesis has:**
-- Dead code detection
-- Unreachable code detection
-- Security vulnerability scanning
-- Code quality metrics
-- Comprehensive checks
-
-**WokeLang has:**
-- Basic linter (`woke lint`)
-- Some static checks
-
-**WokeLang needs:**
-- Advanced analysis passes
-- Data flow analysis
-- Control flow analysis
-- Security checks specific to consent system
-- Capability leak detection
-
-**Implementation Path:**
-```rust
-// src/analyzer.rs
-pub struct StaticAnalyzer {
- checks: Vec,
-}
-
-impl StaticAnalyzer {
- pub fn analyze(&self, ast: &AST) -> Vec { /* ... */ }
-}
-
-pub struct DeadCodePass;
-impl AnalysisPass for DeadCodePass {
- fn run(&self, ast: &AST) -> Vec { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1-2 weeks
-**Dependencies:** None
-
----
-
-### 8. Syntax Highlighting ⚠️ → ✅
-**Phronesis has:**
-- VSCode/VSCodium
-- Vim/Neovim
-- Emacs
-- Sublime Text
-- Kate/KWrite
-- GitHub Linguist
-
-**WokeLang has:**
-- Partial GitHub detection (.gitattributes)
-
-**WokeLang needs:**
-- Complete TextMate grammar
-- Vim syntax file
-- Emacs major mode
-- Sublime syntax
-- Kate XML syntax
-- GitHub Linguist registration
-
-**Implementation Path:**
-```
-syntax/
-├── wokelang.tmLanguage.json # VSCode/Sublime/GitHub
-├── wokelang.vim # Vim/Neovim
-├── wokelang-mode.el # Emacs
-└── wokelang.xml # Kate
-```
-
-**Estimated Effort:** 2-3 days
-**Dependencies:** None (can do immediately)
-
----
-
-### 9. Error Reporter ⚠️ → ✅
-**Phronesis has:**
-- Colorized error messages
-- Source context with line numbers
-- Error suggestions ("did you mean...")
-- Error codes (E0001, E0002, etc.)
-- Related information
-- Help text
-
-**WokeLang has:**
-- Basic error messages
-- Miette integration (partial)
-
-**WokeLang needs:**
-- Comprehensive error catalog
-- Suggestion engine
-- Better formatting
-- Error code system
-
-**Implementation Path:**
-```rust
-// src/diagnostics.rs
-pub struct Diagnostic {
- code: ErrorCode,
- message: String,
- location: SourceLocation,
- suggestions: Vec,
- help: Option,
-}
-
-impl Diagnostic {
- pub fn format_fancy(&self) -> String { /* ... */ }
-}
-```
-
-**Estimated Effort:** 1 week
-**Dependencies:** None
-
----
-
-### 10. Package Manager ❌ → ✅
-**Phronesis has:**
-- `phronesis pkg` command
-- Package registry client
-- Dependency resolution
-- Version management
-- Package publishing
-
-**WokeLang needs:**
-- Package manifest format (wokelang.ncl)
-- Dependency resolver
-- Package registry client
-- Version constraint solver
-- Lock file format
-
-**Implementation Path:**
-```rust
-// src/pkg/manager.rs
-pub struct PackageManager {
- registry: RegistryClient,
- cache: PackageCache,
-}
-
-impl PackageManager {
- pub fn install(&self, name: &str, version: &str) -> Result<()> { /* ... */ }
- pub fn resolve_deps(&self, manifest: &Manifest) -> DependencyGraph { /* ... */ }
-}
-```
-
-**Estimated Effort:** 2-3 weeks
-**Dependencies:** None (but needs registry service eventually)
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Quick Wins (1 week)
-**Goal:** Close easy gaps
-1. ✅ Create TOOLCHAIN-WISHLIST.md (complete)
-2. ✅ Align Justfile structure (complete)
-3. Create syntax highlighting files
-4. Enhanced error messages
-
-### Phase 2: Testing & Quality (1-2 weeks)
-**Goal:** Production readiness
-1. Testing framework
-2. Static analyzer enhancements
-3. Comprehensive test suite
-4. Error reporter improvements
-
-### Phase 3: Developer Tools (6-8 weeks)
-**Goal:** IDE experience
-1. LSP server (3 weeks)
-2. Debugger (2 weeks)
-3. VSCode extension (1 week)
-4. Profiler (1 week)
-5. Doc generator (1 week)
-
-### Phase 4: Ecosystem (2-3 weeks)
-**Goal:** Package ecosystem
-1. Package manager (2 weeks)
-2. Package registry (when ready)
-
----
-
-## Priority Recommendations
-
-**P1 (Start Immediately):**
-- Syntax highlighting (quick win, 2-3 days)
-- Testing framework (essential, 1 week)
-
-**P2 (Next Month):**
-- LSP server (game changer, 2-3 weeks)
-- Debugger (essential dev tool, 1-2 weeks)
-
-**P3 (Next Quarter):**
-- Profiler (performance, 1 week)
-- Doc generator (onboarding, 1 week)
-- Static analyzer (quality, 1-2 weeks)
-
-**P4 (As Needed):**
-- Package manager (ecosystem growth, 2-3 weeks)
-- VSCode extension (after LSP, 3-4 days)
-
----
-
-## Success Metrics
-
-**Toolchain Parity Achieved When:**
-- ✅ LSP server operational
-- ✅ Debugger with breakpoints working
-- ✅ Testing framework running test suites
-- ✅ Profiler generating reports
-- ✅ Docs auto-generated from code
-- ✅ VSCode extension published
-- ✅ Package manager functional
-
-**Timeline to Parity:** 10-12 weeks (focused development)
-
----
-
-## Resources Needed
-
-**Development:**
-- 1 full-time developer: 10-12 weeks
-- OR 2 part-time developers: 5-6 weeks (parallelizable)
-
-**Skills Required:**
-- Rust programming
-- LSP protocol knowledge
-- Compiler/interpreter development
-- VSCode extension API
-- Package management systems
-
----
-
-**Maintainer:** Jonathan D.A. Jewell
-**Date:** 2026-02-01
-**License:** MPL-2.0
-**Related:** TOOLCHAIN-WISHLIST.md, NEXT-STEPS.adoc
diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc
new file mode 100644
index 0000000..c28c31e
--- /dev/null
+++ b/PROOF-NEEDS.adoc
@@ -0,0 +1,51 @@
+== PROOF-NEEDS.md
+
+=== Current State
+
+* *LOC*: ~27,300
+* *Languages*: OCaml, Rust, ReScript, Lean4, Idris2, Zig
+* *Existing ABI proofs*: `+src/abi/*.idr+` (template-level)
+* *Existing verification*: `+docs/proofs/verification/WokeLang.lean+` —
+Lean4 proofs exist, 12 `+sorry+` occurrences previously eliminated
+* *Dangerous patterns*: None remaining (Lean4 file mentions sorry
+elimination is complete)
+
+=== What Needs Proving
+
+==== Lean4 Proof Completeness Audit
+
+* `+WokeLang.lean+` claims all 12 `+sorry+` eliminated — verify this is
+still true after any subsequent changes
+* Audit: do the Lean4 proofs cover the full type system or only a
+subset?
+
+==== OCaml Core (core/)
+
+* `+ast.ml+`, `+eval.ml+`, `+main.ml+` — the runtime evaluator
+* If Lean4 proofs cover the type system but not evaluation, there is a
+gap
+* Prove: evaluation semantics match the Lean4 specification
+
+==== WASM Backend (compiler/wokelang-wasm/src/lib.rs)
+
+* Compilation to WASM should preserve the properties proven in Lean4
+* Prove: WASM codegen produces programs with the same observable
+behaviour
+
+==== Fuzz Coverage
+
+* `+fuzz/fuzz_lexer.ml+`, `+fuzz/fuzz_parser.ml+`,
+`+fuzz/fuzz_targets/fuzz_input.rs+`
+* Fuzzing is a good complement but does not replace proofs for the core
+semantics
+
+=== Recommended Prover
+
+* *Lean4* (already in use — extend to cover evaluation and compilation)
+* *Idris2* for ABI layer
+
+=== Priority
+
+*MEDIUM* — Good existing proof coverage in Lean4. Focus on extending
+proofs to evaluation and WASM compilation rather than starting from
+scratch. The sorry-free status needs periodic re-verification.
diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md
deleted file mode 100644
index d31127c..0000000
--- a/PROOF-NEEDS.md
+++ /dev/null
@@ -1,40 +0,0 @@
-
-# PROOF-NEEDS.md
-## Current State
-
-- **LOC**: ~27,300
-- **Languages**: OCaml, Rust, ReScript, Lean4, Idris2, Zig
-- **Existing ABI proofs**: `src/abi/*.idr` (template-level)
-- **Existing verification**: `docs/proofs/verification/WokeLang.lean` — Lean4 proofs exist, 12 `sorry` occurrences previously eliminated
-- **Dangerous patterns**: None remaining (Lean4 file mentions sorry elimination is complete)
-
-## What Needs Proving
-
-### Lean4 Proof Completeness Audit
-- `WokeLang.lean` claims all 12 `sorry` eliminated — verify this is still true after any subsequent changes
-- Audit: do the Lean4 proofs cover the full type system or only a subset?
-
-### OCaml Core (core/)
-- `ast.ml`, `eval.ml`, `main.ml` — the runtime evaluator
-- If Lean4 proofs cover the type system but not evaluation, there is a gap
-- Prove: evaluation semantics match the Lean4 specification
-
-### WASM Backend (compiler/wokelang-wasm/src/lib.rs)
-- Compilation to WASM should preserve the properties proven in Lean4
-- Prove: WASM codegen produces programs with the same observable behaviour
-
-### Fuzz Coverage
-- `fuzz/fuzz_lexer.ml`, `fuzz/fuzz_parser.ml`, `fuzz/fuzz_targets/fuzz_input.rs`
-- Fuzzing is a good complement but does not replace proofs for the core semantics
-
-## Recommended Prover
-
-- **Lean4** (already in use — extend to cover evaluation and compilation)
-- **Idris2** for ABI layer
-
-## Priority
-
-**MEDIUM** — Good existing proof coverage in Lean4. Focus on extending proofs to evaluation and WASM compilation rather than starting from scratch. The sorry-free status needs periodic re-verification.
diff --git a/RESUME.adoc b/RESUME.adoc
new file mode 100644
index 0000000..371125e
--- /dev/null
+++ b/RESUME.adoc
@@ -0,0 +1,151 @@
+== RESUME — grammar formal-proofs work
+
+Pick-up notes for continuing the
+`+claude/v2-grammar-proofs-audit-1yqgxh+` work on another machine
+(e.g. the Claude Code desktop app). Everything here is committed to that
+branch, so it travels with the code.
+
+=== Where the work stands
+
+Goal: machine-check every necessary/sufficient proof for the grammar
+that exists in this repo (`+grammar/wokelang.ebnf+`), install the
+provers, and report only proofs that actually run. The grammar was
+reconciled to one source of truth, and the proof obligations were
+mechanized in Lean 4 (mirrored to Coq where sensible).
+
+*Open PR:* #106 — _CFL pumping lemma, machine-checked from scratch in
+Lean_ (branch `+claude/v2-grammar-proofs-audit-1yqgxh+`).
+
+*Merged on the way here:* #102 (parser metatheory + grammar
+reconciliation), #103 (no-left-recursion + lexer + classification,
+Lean+Coq), #104 (Coq parser port + §7.1 not-regular), #105 (§7.3 CFL
+positive closure).
+
+=== Proof inventory — all verified green (last full run in the cloud container)
+
+Single-file, Mathlib-free. `+lean +` / `+coqc +` must exit 0
+with no errors.
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|File |What it proves |Status
+|`+docs/proofs/verification/WokeLang.lean+` / `+.v+` |core language
+metatheory (sorry-audit resolved) |✅
+
+|`+docs/proofs/verification/WokeGrammar.lean+` |Pratt-parser metatheory:
+prefix/completeness/determinism/injectivity |✅
+
+|`+docs/proofs/verification/WokeGrammarStructure.lean+` / `+.v+`
+|no-left-recursion (+ found a real spec bug in `+pattern+`), lexer
+maximal-munch + keyword priority, CFG/¬LL(1)/LL(2) classification |✅
+
+|`+docs/proofs/verification/WokeGrammarParser.v+` |Coq port of the
+parser metatheory |✅
+
+|`+docs/proofs/verification/WokeGrammarRegular.lean+` |§7.1 not-regular:
+bespoke pigeonhole + `+Fin k+` DFA + fooling set on `+aⁿbⁿ+` |✅
+
+|`+docs/proofs/verification/WokeGrammarCFL.lean+` |§7.3 CFL *positive*
+closure under ∪, ·, * |✅
+
+|`+docs/proofs/verification/WokeGrammarPumping.lean+` |*CFL pumping
+lemma* `+cfl_pumping+` (the Mathlib-gap result) |✅
+|===
+
+Trust base for the proofs: the standard classical kernel constants only
+(`+propext+`, `+Classical.choice+`, `+Quot.sound+`) — no holes, no
+project-specific assumptions. Confirm with Lean’s kernel-dependency
+printout per file.
+
+The claim-by-claim map lives in
+`+docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md+`.
+
+=== How to re-run the provers locally
+
+The provers are NOT in the repo — they were installed in the (ephemeral)
+cloud container. Reinstall the pinned versions locally.
+
+==== Lean 4.30.0 (pinned by `+docs/proofs/verification/lean-toolchain+`)
+
+The exact, Mathlib-free steps are in
+`+.github/workflows/lean-proofs.yml+`:
+
+[source,sh]
+----
+ver=4.30.0
+curl -sSL -o /tmp/lean.tar.zst \
+ "https://github.com/leanprover/lean4/releases/download/v${ver}/lean-${ver}-linux.tar.zst"
+sudo mkdir -p /opt/lean
+sudo tar --use-compress-program=unzstd -xf /tmp/lean.tar.zst -C /opt/lean
+export PATH="/opt/lean/lean-${ver}-linux/bin:$PATH" # use the macOS/win tarball on those OSes
+----
+
+Then, from the repo root:
+
+[source,sh]
+----
+for f in WokeLang WokeGrammar WokeGrammarStructure WokeGrammarRegular WokeGrammarCFL WokeGrammarPumping; do
+ lean docs/proofs/verification/$f.lean && echo "OK $f"
+done
+----
+
+==== Coq 8.18.0
+
+[source,sh]
+----
+# install coq 8.18.0 (opam: `opam pin add coq 8.18.0`, or your platform package)
+cd docs/proofs/verification
+for f in WokeLang WokeGrammarStructure WokeGrammarParser; do coqc $f.v && echo "OK $f"; done
+rm -f *.vo *.vok *.vos *.glob .*.aux # clean build artifacts
+----
+
+=== §7.3 non-closure — status
+
+Done (in `+WokeGrammarPumping.lean+`):
+
+[arabic]
+. *Finiteness-aware `+IsCFL+`* — a language is CF iff some ε-free BNF
+grammar with an `+enum+`/`+card+` nonterminal bound generates exactly it
+(matches `+cfl_pumping+`).
+. *`+aⁿbⁿcⁿ ∉ CFL+`* (`+anbncn_not_cfl+`) — via `+cfl_pumping+`: pumping
+down to `+i = 0+` forces `+count_a = count_b = count_c+` in the deleted
+part, so the window spans an `+a+` and a `+c+`; the positional core
+(`+prefix_pure+`, `+abc_window+`) then gives `+|vwx| > p+`,
+contradicting `+|vwx| ≤ p+`. This is the canonical non-CFL and the crux
+of the ∩/¬ non-closure result.
+. *The explicit ∩ non-closure statement* (`+cfl_not_closed_inter+`) —
+the two witness CFLs `+L₁ = {aⁱbⁱcʲ}+` and `+L₂ = {aᵐbⁿcⁿ}+` are each
+proved context-free by an explicit ε-free BNF grammar (`+R1+`, `+R2+`)
+with full exact generation (soundness via tree inversion
+`+sound_all1+`/`+sound_all2+`, completeness via tree builders), and
+`+L₁ ∩ L₂ = {aⁿbⁿcⁿ}+` (`+inter_eq+`) is discharged by
+`+anbncn_not_cfl+`. *Done.*
+
+§7 is now fully machine-checked end-to-end. The only further extension
+one could add is closure under *complement* as a standalone theorem,
+which needs CFL ∪-closure for this BNF `+IsCFL+` (the positive closure
+exists in `+WokeGrammarCFL.lean+` under a relation-based `+IsCFL+`); the
+De Morgan corollary is noted in `+cfl_not_closed_inter+`’s docstring.
+
+Plan: land it as its own follow-up PR (incremental, same as the pumping
+lemma).
+
+=== CI notes
+
+On PR #106, the genuinely-relevant checks are green (Trusted-base
+reduction policy; the Lean/Coq compile gates). Three checks are red but
+are *pre-existing infrastructure failures unrelated to these proofs*,
+and every prior merged PR (#102–#105) carried them too:
+
+* *Licence consistency* — root `+LICENSE+` SPDX mismatch.
+* *Workflow security linter* — a `+trufflehog@main+` unpinned-action
+finding.
+* *Hypatia Neurosymbolic Analysis* — scanner infrastructure.
+
+=== Moving this session to desktop
+
+Per the Claude Code docs, use *teleport* to carry the conversation
+context + branch + uncommitted changes from web into the local CLI /
+desktop app: `+claude --teleport +` (one-way: web → local).
+See https://code.claude.com/docs/en/claude-code-on-the-web. Even without
+it, the branch and PR #106 hold all the work.
diff --git a/RESUME.md b/RESUME.md
deleted file mode 100644
index a57dbfc..0000000
--- a/RESUME.md
+++ /dev/null
@@ -1,124 +0,0 @@
-
-
-
-# RESUME — grammar formal-proofs work
-
-Pick-up notes for continuing the `claude/v2-grammar-proofs-audit-1yqgxh` work on
-another machine (e.g. the Claude Code desktop app). Everything here is committed
-to that branch, so it travels with the code.
-
-## Where the work stands
-
-Goal: machine-check every necessary/sufficient proof for the grammar that exists
-in this repo (`grammar/wokelang.ebnf`), install the provers, and report only
-proofs that actually run. The grammar was reconciled to one source of truth, and
-the proof obligations were mechanized in Lean 4 (mirrored to Coq where sensible).
-
-**Open PR:** #106 — *CFL pumping lemma, machine-checked from scratch in Lean*
-(branch `claude/v2-grammar-proofs-audit-1yqgxh`).
-
-**Merged on the way here:** #102 (parser metatheory + grammar reconciliation),
-#103 (no-left-recursion + lexer + classification, Lean+Coq), #104 (Coq parser
-port + §7.1 not-regular), #105 (§7.3 CFL positive closure).
-
-## Proof inventory — all verified green (last full run in the cloud container)
-
-Single-file, Mathlib-free. `lean ` / `coqc ` must exit 0 with no errors.
-
-| File | What it proves | Status |
-|---|---|---|
-| `docs/proofs/verification/WokeLang.lean` / `.v` | core language metatheory (sorry-audit resolved) | ✅ |
-| `docs/proofs/verification/WokeGrammar.lean` | Pratt-parser metatheory: prefix/completeness/determinism/injectivity | ✅ |
-| `docs/proofs/verification/WokeGrammarStructure.lean` / `.v` | no-left-recursion (+ found a real spec bug in `pattern`), lexer maximal-munch + keyword priority, CFG/¬LL(1)/LL(2) classification | ✅ |
-| `docs/proofs/verification/WokeGrammarParser.v` | Coq port of the parser metatheory | ✅ |
-| `docs/proofs/verification/WokeGrammarRegular.lean` | §7.1 not-regular: bespoke pigeonhole + `Fin k` DFA + fooling set on `aⁿbⁿ` | ✅ |
-| `docs/proofs/verification/WokeGrammarCFL.lean` | §7.3 CFL **positive** closure under ∪, ·, * | ✅ |
-| `docs/proofs/verification/WokeGrammarPumping.lean` | **CFL pumping lemma** `cfl_pumping` (the Mathlib-gap result) | ✅ |
-
-Trust base for the proofs: the standard classical kernel constants only
-(`propext`, `Classical.choice`, `Quot.sound`) — no holes, no project-specific
-assumptions. Confirm with Lean's kernel-dependency printout per file.
-
-The claim-by-claim map lives in
-`docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md`.
-
-## How to re-run the provers locally
-
-The provers are NOT in the repo — they were installed in the (ephemeral) cloud
-container. Reinstall the pinned versions locally.
-
-### Lean 4.30.0 (pinned by `docs/proofs/verification/lean-toolchain`)
-
-The exact, Mathlib-free steps are in `.github/workflows/lean-proofs.yml`:
-
-```sh
-ver=4.30.0
-curl -sSL -o /tmp/lean.tar.zst \
- "https://github.com/leanprover/lean4/releases/download/v${ver}/lean-${ver}-linux.tar.zst"
-sudo mkdir -p /opt/lean
-sudo tar --use-compress-program=unzstd -xf /tmp/lean.tar.zst -C /opt/lean
-export PATH="/opt/lean/lean-${ver}-linux/bin:$PATH" # use the macOS/win tarball on those OSes
-```
-
-Then, from the repo root:
-
-```sh
-for f in WokeLang WokeGrammar WokeGrammarStructure WokeGrammarRegular WokeGrammarCFL WokeGrammarPumping; do
- lean docs/proofs/verification/$f.lean && echo "OK $f"
-done
-```
-
-### Coq 8.18.0
-
-```sh
-# install coq 8.18.0 (opam: `opam pin add coq 8.18.0`, or your platform package)
-cd docs/proofs/verification
-for f in WokeLang WokeGrammarStructure WokeGrammarParser; do coqc $f.v && echo "OK $f"; done
-rm -f *.vo *.vok *.vos *.glob .*.aux # clean build artifacts
-```
-
-## §7.3 non-closure — status
-
-Done (in `WokeGrammarPumping.lean`):
-
-1. **Finiteness-aware `IsCFL`** — a language is CF iff some ε-free BNF grammar with
- an `enum`/`card` nonterminal bound generates exactly it (matches `cfl_pumping`).
-2. **`aⁿbⁿcⁿ ∉ CFL`** (`anbncn_not_cfl`) — via `cfl_pumping`: pumping down to
- `i = 0` forces `count_a = count_b = count_c` in the deleted part, so the window
- spans an `a` and a `c`; the positional core (`prefix_pure`, `abc_window`) then
- gives `|vwx| > p`, contradicting `|vwx| ≤ p`. This is the canonical non-CFL and
- the crux of the ∩/¬ non-closure result.
-
-3. **The explicit ∩ non-closure statement** (`cfl_not_closed_inter`) — the two
- witness CFLs `L₁ = {aⁱbⁱcʲ}` and `L₂ = {aᵐbⁿcⁿ}` are each proved context-free by
- an explicit ε-free BNF grammar (`R1`, `R2`) with full exact generation
- (soundness via tree inversion `sound_all1`/`sound_all2`, completeness via tree
- builders), and `L₁ ∩ L₂ = {aⁿbⁿcⁿ}` (`inter_eq`) is discharged by
- `anbncn_not_cfl`. **Done.**
-
-§7 is now fully machine-checked end-to-end. The only further extension one could
-add is closure under **complement** as a standalone theorem, which needs CFL
-∪-closure for this BNF `IsCFL` (the positive closure exists in
-`WokeGrammarCFL.lean` under a relation-based `IsCFL`); the De Morgan corollary is
-noted in `cfl_not_closed_inter`'s docstring.
-
-Plan: land it as its own follow-up PR (incremental, same as the pumping lemma).
-
-## CI notes
-
-On PR #106, the genuinely-relevant checks are green (Trusted-base reduction
-policy; the Lean/Coq compile gates). Three checks are red but are **pre-existing
-infrastructure failures unrelated to these proofs**, and every prior merged PR
-(#102–#105) carried them too:
-
-- **Licence consistency** — root `LICENSE` SPDX mismatch.
-- **Workflow security linter** — a `trufflehog@main` unpinned-action finding.
-- **Hypatia Neurosymbolic Analysis** — scanner infrastructure.
-
-## Moving this session to desktop
-
-Per the Claude Code docs, use **teleport** to carry the conversation context +
-branch + uncommitted changes from web into the local CLI / desktop app:
-`claude --teleport ` (one-way: web → local). See
-. Even without it, the
-branch and PR #106 hold all the work.
diff --git a/SECURITY.adoc b/SECURITY.adoc
new file mode 100644
index 0000000..e47fdd9
--- /dev/null
+++ b/SECURITY.adoc
@@ -0,0 +1,16 @@
+== Security Policy
+
+=== Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+*Email:* j.d.a.jewell@open.ac.uk
+
+*Please include:* - Description of the vulnerability - Steps to
+reproduce - Potential impact
+
+*Response timeline:* - Acknowledgement within 48 hours - Initial
+assessment within 7 days - Fix or mitigation within 90 days
+
+*Safe harbour:* We will not pursue legal action against security
+researchers who follow responsible disclosure.
diff --git a/SECURITY.md b/SECURITY.md
deleted file mode 100644
index c7c239f..0000000
--- a/SECURITY.md
+++ /dev/null
@@ -1,23 +0,0 @@
-
-# Security Policy
-
-## Reporting a Vulnerability
-
-If you discover a security vulnerability, please report it responsibly.
-
-**Email:** j.d.a.jewell@open.ac.uk
-
-**Please include:**
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-
-**Response timeline:**
-- Acknowledgement within 48 hours
-- Initial assessment within 7 days
-- Fix or mitigation within 90 days
-
-**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure.
diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc
new file mode 100644
index 0000000..5a096b9
--- /dev/null
+++ b/TEST-NEEDS.adoc
@@ -0,0 +1,187 @@
+== TEST-NEEDS: wokelang
+
+=== CRG Grade: C — ACHIEVED 2026-04-04
+
+=== Current State (Updated 2026-04-04)
+
+[width="100%",cols="40%,26%,34%",options="header",]
+|===
+|Category |Count |Details
+|*Source modules* |54 |Rust: ast (2), codegen, dap, ffi (2), formatter,
+interpreter (2), lexer (2), linter, lsp (10: backend, document,
+handlers/5, mod, stdlib_metadata, symbols, utils), lib, parser + 3
+Idris2 ABI
+
+|*Unit tests (Rust inline)* |37 |interpreter=13, parser=8,
+lsp_integration=8, lexer=4, linter=3, formatter=1
+
+|*Unit tests (OCaml)* |3 files |test_lexer.ml (~213 refs),
+test_parser.ml (~347 refs), test_wokelang.ml (~114 refs)
+
+|*Integration tests* |1 |lsp_integration_test.rs (8 tests)
+
+|*E2E tests* |12 |e2e_full_pipeline_test.rs (validates Lex → Parse →
+TypeCheck → Interpret)
+
+|*Conformance tests* |15 |7 consent-focused + 8 existing tests in
+test/conformance/
+
+|*LSP handler tests* |12 |lsp_handler_test.rs (completion, hover,
+definition, LSP integration)
+
+|*Codegen tests* |8 |codegen_test.rs (all passing)
+
+|*Property tests* |6 |property_test.rs (using proptest)
+
+|*Benchmarks* |3 files |vm_bench.rs (Rust), bench_lexer.ml,
+bench_parser.ml (OCaml)
+
+|*Fuzz tests* |0 |Removed placeholder.txt (fake fuzz coverage)
+|===
+
+=== Status Summary
+
+==== Completed (CRG C Target)
+
+* [x] Consent/permission conformance tests — 8 new `+.wl+` test
+programs:
+** `+consent_grant.wl+` (existing)
+** `+consent_scope.wl+` (existing)
+** `+consent_revocation.wl+` (NEW)
+** `+consent_inheritance.wl+` (NEW)
+** `+consent_nesting.wl+` (NEW)
+** `+consent_multiple_permissions.wl+` (NEW)
+** `+consent_with_variables.wl+` (NEW)
+** `+consent_with_string_operations.wl+` (NEW)
+** `+consent_with_loops.wl+` (NEW)
+** `+consent_with_arrays.wl+` (NEW)
+* [x] E2E test (`+tests/e2e_full_pipeline_test.rs+`) — 12 tests
+validating complete pipeline (Lex → Parse → TypeCheck → Interpret)
+* [x] Codegen tests (`+tests/codegen_test.rs+`) — 8 tests covering code
+generation for various language constructs
+* [x] Property-based tests (`+tests/property_test.rs+`) — 6 tests using
+proptest
+* [x] LSP handler coverage — 12 additional LSP tests (completion, hover,
+definition, type environment)
+* [x] Conformance test runner (`+tests/run_conformance.sh+`) — bash
+script for running all `+.wl+` conformance tests
+* [x] Removed fake fuzz placeholder (`+tests/fuzz/placeholder.txt+`)
+* [x] Fixed RuntimeError compilation issue (added `+new()+` impl)
+* [x] Fixed missing `+dap+` module export in `+lib.rs+`
+
+==== Test Results
+
+* *Inline Rust tests*: 170 passing, 3 pre-existing failures (not
+blocking C grade)
+* *E2E tests*: 12 passing
+* *Codegen tests*: 8 passing
+* *LSP handler tests*: 12 passing
+* *Property tests*: 6 passing
+* *Total new tests*: 38 passing (across new suites)
+
+==== Pre-existing Failures (NOT blocking C grade)
+
+These 3 failures existed before this blitz: 1.
+`+parser::tests::test_parse_pattern_matching+` — parser pattern matching
+syntax edge case 2. `+typechecker::tests::test_type_checker_new+` — type
+checker environment assertion 3.
+`+vm::tests::test_run_vm_function_call+` — unimplemented opcode
+
+=== What’s Addressed
+
+==== Consent-Aware Language Coverage
+
+WokeLang’s defining feature (consent/permission system) is now
+thoroughly tested: - Grant and revocation - Permission inheritance
+across scopes - Nested consent contexts (3+ levels) - Multiple
+independent permissions - Variables modified within consent blocks -
+String operations within consent - Loops within consent blocks - Array
+operations within consent blocks
+
+==== Full Pipeline Validation
+
+E2E tests validate the entire compilation pipeline: - Lexical analysis
+(tokenization) - Parsing (AST construction) - Type checking -
+Interpretation/execution - Error handling without crashes
+
+==== Code Generation Verification
+
+Codegen tests ensure bytecode compilation works for: - Simple arithmetic
+- Function definitions - Conditionals - Loops - Arrays - Consent blocks
+- Program structure preservation
+
+==== LSP Integration
+
+Enhanced LSP handler tests for critical features: - Completion handler
+with keywords and consent operations - Hover handler on function names
+and builtin functions - Definition handler for function definitions -
+Type environment caching - Error diagnostics
+
+=== Remaining Gaps (Beyond CRG C)
+
+* Fuzzing still not implemented (removed fake placeholder)
+* DAP (debugger) server integration tests
+* Concurrent interpreter execution tests
+* Performance regression benchmarks
+* Cross-language validation (Rust/OCaml dual codebase)
+
+=== Build Status
+
+....
+cargo test --lib → 170 passing, 3 failing (pre-existing)
+cargo test --test e2e_full_pipeline_test → 12 passing
+cargo test --test codegen_test → 8 passing
+cargo test --test lsp_handler_test → 12 passing
+cargo test --test property_test → 6 passing
+cargo test --test lsp_integration_test → (existing 8 tests)
+....
+
+=== Files Modified/Created
+
+==== New Test Files
+
+* `+tests/e2e_full_pipeline_test.rs+` — 12 E2E tests
+* `+tests/codegen_test.rs+` — 8 codegen tests
+* `+tests/property_test.rs+` — 6 property-based tests
+* `+tests/lsp_handler_test.rs+` — 12 LSP handler tests
+* `+tests/run_conformance.sh+` — bash runner for conformance tests
+
+==== New Conformance Tests
+
+* `+test/conformance/consent_revocation.wl+`
+* `+test/conformance/consent_inheritance.wl+`
+* `+test/conformance/consent_nesting.wl+`
+* `+test/conformance/consent_multiple_permissions.wl+`
+* `+test/conformance/consent_with_variables.wl+`
+* `+test/conformance/consent_with_string_operations.wl+`
+* `+test/conformance/consent_with_loops.wl+`
+* `+test/conformance/consent_with_arrays.wl+`
+
+==== Modified Files
+
+* `+src/interpreter/mod.rs+` — Added `+RuntimeError::new()+` impl
+* `+src/lib.rs+` — Added `+pub mod dap+` export
+* `+Cargo.toml+` — Added `+proptest = "1.4"+` to dev-dependencies
+* `+tests/fuzz/placeholder.txt+` — REMOVED (fake fuzz coverage)
+
+=== Compliance
+
+==== SPDX Headers
+
+* All new test files: `+SPDX-License-Identifier: CC-BY-SA-4.0+`
+* All new conformance test programs:
+`+SPDX-License-Identifier: CC-BY-SA-4.0+`
+* Test runner script: SPDX header included
+
+==== Author Attribution
+
+* Git author: Jonathan D.A. Jewell
+6759885+hyperpolymath@users.noreply.github.com
+* All new files include proper copyright header
+
+==== CRG V2.0 Mapping
+
+* *Grade*: C (was D, now C)
+* *Test coverage*: Unit + smoke + build + P2P + E2E + reflexive +
+contract + aspect
+* *Benchmarks*: Baselined (vm_bench.rs, bench_lexer.ml, bench_parser.ml)
diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md
deleted file mode 100644
index 5fad971..0000000
--- a/TEST-NEEDS.md
+++ /dev/null
@@ -1,156 +0,0 @@
-
-# TEST-NEEDS: wokelang
-## CRG Grade: C — ACHIEVED 2026-04-04
-
-## Current State (Updated 2026-04-04)
-
-| Category | Count | Details |
-|----------|-------|---------|
-| **Source modules** | 54 | Rust: ast (2), codegen, dap, ffi (2), formatter, interpreter (2), lexer (2), linter, lsp (10: backend, document, handlers/5, mod, stdlib_metadata, symbols, utils), lib, parser + 3 Idris2 ABI |
-| **Unit tests (Rust inline)** | 37 | interpreter=13, parser=8, lsp_integration=8, lexer=4, linter=3, formatter=1 |
-| **Unit tests (OCaml)** | 3 files | test_lexer.ml (~213 refs), test_parser.ml (~347 refs), test_wokelang.ml (~114 refs) |
-| **Integration tests** | 1 | lsp_integration_test.rs (8 tests) |
-| **E2E tests** | 12 | e2e_full_pipeline_test.rs (validates Lex → Parse → TypeCheck → Interpret) |
-| **Conformance tests** | 15 | 7 consent-focused + 8 existing tests in test/conformance/ |
-| **LSP handler tests** | 12 | lsp_handler_test.rs (completion, hover, definition, LSP integration) |
-| **Codegen tests** | 8 | codegen_test.rs (all passing) |
-| **Property tests** | 6 | property_test.rs (using proptest) |
-| **Benchmarks** | 3 files | vm_bench.rs (Rust), bench_lexer.ml, bench_parser.ml (OCaml) |
-| **Fuzz tests** | 0 | Removed placeholder.txt (fake fuzz coverage) |
-
-## Status Summary
-
-### Completed (CRG C Target)
-- [x] Consent/permission conformance tests — 8 new `.wl` test programs:
- - `consent_grant.wl` (existing)
- - `consent_scope.wl` (existing)
- - `consent_revocation.wl` (NEW)
- - `consent_inheritance.wl` (NEW)
- - `consent_nesting.wl` (NEW)
- - `consent_multiple_permissions.wl` (NEW)
- - `consent_with_variables.wl` (NEW)
- - `consent_with_string_operations.wl` (NEW)
- - `consent_with_loops.wl` (NEW)
- - `consent_with_arrays.wl` (NEW)
-- [x] E2E test (`tests/e2e_full_pipeline_test.rs`) — 12 tests validating complete pipeline (Lex → Parse → TypeCheck → Interpret)
-- [x] Codegen tests (`tests/codegen_test.rs`) — 8 tests covering code generation for various language constructs
-- [x] Property-based tests (`tests/property_test.rs`) — 6 tests using proptest
-- [x] LSP handler coverage — 12 additional LSP tests (completion, hover, definition, type environment)
-- [x] Conformance test runner (`tests/run_conformance.sh`) — bash script for running all `.wl` conformance tests
-- [x] Removed fake fuzz placeholder (`tests/fuzz/placeholder.txt`)
-- [x] Fixed RuntimeError compilation issue (added `new()` impl)
-- [x] Fixed missing `dap` module export in `lib.rs`
-
-### Test Results
-- **Inline Rust tests**: 170 passing, 3 pre-existing failures (not blocking C grade)
-- **E2E tests**: 12 passing
-- **Codegen tests**: 8 passing
-- **LSP handler tests**: 12 passing
-- **Property tests**: 6 passing
-- **Total new tests**: 38 passing (across new suites)
-
-### Pre-existing Failures (NOT blocking C grade)
-These 3 failures existed before this blitz:
-1. `parser::tests::test_parse_pattern_matching` — parser pattern matching syntax edge case
-2. `typechecker::tests::test_type_checker_new` — type checker environment assertion
-3. `vm::tests::test_run_vm_function_call` — unimplemented opcode
-
-## What's Addressed
-
-### Consent-Aware Language Coverage
-WokeLang's defining feature (consent/permission system) is now thoroughly tested:
-- Grant and revocation
-- Permission inheritance across scopes
-- Nested consent contexts (3+ levels)
-- Multiple independent permissions
-- Variables modified within consent blocks
-- String operations within consent
-- Loops within consent blocks
-- Array operations within consent blocks
-
-### Full Pipeline Validation
-E2E tests validate the entire compilation pipeline:
-- Lexical analysis (tokenization)
-- Parsing (AST construction)
-- Type checking
-- Interpretation/execution
-- Error handling without crashes
-
-### Code Generation Verification
-Codegen tests ensure bytecode compilation works for:
-- Simple arithmetic
-- Function definitions
-- Conditionals
-- Loops
-- Arrays
-- Consent blocks
-- Program structure preservation
-
-### LSP Integration
-Enhanced LSP handler tests for critical features:
-- Completion handler with keywords and consent operations
-- Hover handler on function names and builtin functions
-- Definition handler for function definitions
-- Type environment caching
-- Error diagnostics
-
-## Remaining Gaps (Beyond CRG C)
-- Fuzzing still not implemented (removed fake placeholder)
-- DAP (debugger) server integration tests
-- Concurrent interpreter execution tests
-- Performance regression benchmarks
-- Cross-language validation (Rust/OCaml dual codebase)
-
-## Build Status
-```
-cargo test --lib → 170 passing, 3 failing (pre-existing)
-cargo test --test e2e_full_pipeline_test → 12 passing
-cargo test --test codegen_test → 8 passing
-cargo test --test lsp_handler_test → 12 passing
-cargo test --test property_test → 6 passing
-cargo test --test lsp_integration_test → (existing 8 tests)
-```
-
-## Files Modified/Created
-
-### New Test Files
-- `tests/e2e_full_pipeline_test.rs` — 12 E2E tests
-- `tests/codegen_test.rs` — 8 codegen tests
-- `tests/property_test.rs` — 6 property-based tests
-- `tests/lsp_handler_test.rs` — 12 LSP handler tests
-- `tests/run_conformance.sh` — bash runner for conformance tests
-
-### New Conformance Tests
-- `test/conformance/consent_revocation.wl`
-- `test/conformance/consent_inheritance.wl`
-- `test/conformance/consent_nesting.wl`
-- `test/conformance/consent_multiple_permissions.wl`
-- `test/conformance/consent_with_variables.wl`
-- `test/conformance/consent_with_string_operations.wl`
-- `test/conformance/consent_with_loops.wl`
-- `test/conformance/consent_with_arrays.wl`
-
-### Modified Files
-- `src/interpreter/mod.rs` — Added `RuntimeError::new()` impl
-- `src/lib.rs` — Added `pub mod dap` export
-- `Cargo.toml` — Added `proptest = "1.4"` to dev-dependencies
-- `tests/fuzz/placeholder.txt` — REMOVED (fake fuzz coverage)
-
-## Compliance
-
-### SPDX Headers
-- All new test files: `SPDX-License-Identifier: CC-BY-SA-4.0`
-- All new conformance test programs: `SPDX-License-Identifier: CC-BY-SA-4.0`
-- Test runner script: SPDX header included
-
-### Author Attribution
-- Git author: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
-- All new files include proper copyright header
-
-### CRG V2.0 Mapping
-- **Grade**: C (was D, now C)
-- **Test coverage**: Unit + smoke + build + P2P + E2E + reflexive + contract + aspect
-- **Benchmarks**: Baselined (vm_bench.rs, bench_lexer.ml, bench_parser.ml)
diff --git a/TOOLCHAIN-WISHLIST.adoc b/TOOLCHAIN-WISHLIST.adoc
new file mode 100644
index 0000000..d4facf0
--- /dev/null
+++ b/TOOLCHAIN-WISHLIST.adoc
@@ -0,0 +1,582 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: 2026
+Jonathan D.A. Jewell
+
+== WokeLang Toolchain Wishlist
+
+=== Missing Components for Production-Grade Language
+
+*Current Status:* Core language complete (85% overall)
+
+*Existing Tools:* ✅ - Lexer, Parser, AST - Type System (Hindley-Milner
+inference) - Interpreter (tree-walking) - Bytecode VM + Compiler - REPL
+(interactive mode) - CLI (`+woke run/typecheck/lint/parse/tokenize+`) -
+Consent/Capability System (runtime enforcement) - Worker System (basic
+concurrency) - Standard Library (partial integration) - Examples/Demos
+
+'''''
+
+=== High Priority (Production Essentials)
+
+==== 1. Language Server Protocol (LSP) 📡
+
+*Impact:* IDE integration, developer experience *Effort:* 2-3 weeks
+
+*Features:* - Go to definition - Find references - Hover documentation -
+Auto-completion - Inline diagnostics (errors/warnings) - Code actions
+(quick fixes) - Rename symbol - Signature help
+
+*Implementation:*
+
+[source,rust]
+----
+// src/lsp/server.rs
+pub struct LspServer {
+ // JSON-RPC server
+ // textDocument/didOpen, didChange, didSave
+ // textDocument/completion
+ // textDocument/hover
+ // textDocument/definition
+ // textDocument/references
+ // textDocument/formatting
+}
+----
+
+*Why Critical:* - VSCode/Neovim/Emacs integration - Real-time error
+checking - Autocomplete for stdlib functions - Standard for modern
+languages
+
+*Deliverable:* `+woke lsp+` command
+
+'''''
+
+==== 2. Debugger 🐛
+
+*Impact:* Program development, troubleshooting *Effort:* 1-2 weeks
+
+*Features:* - Breakpoints in WokeLang code - Step-through execution -
+Variable inspection - Watch expressions - Call stack - Worker thread
+debugging
+
+*Implementation:*
+
+[source,rust]
+----
+// src/debugger.rs
+pub struct Debugger {
+ // Instrument AST with breakpoints
+ // Step-by-step evaluation
+ // State inspection at each step
+ // Integration with existing interpreter
+}
+----
+
+*Why Critical:* - Complex programs hard to debug - Worker concurrency
+needs investigation - Consent flow debugging
+
+*Deliverable:* `+woke debug program.woke+`
+
+'''''
+
+==== 3. Testing Framework 🧪
+
+*Impact:* Code reliability, CI/CD *Effort:* 1 week
+
+*Features:* - Unit tests for WokeLang code - Property-based testing -
+Consent scenario testing - Worker concurrency tests - Coverage reporting
+
+*Implementation:*
+
+[source,rust]
+----
+// src/test_framework.rs
+pub struct TestFramework {
+ // Test macro expansion
+ // Assertion functions
+ // Test runner
+ // Coverage analysis
+}
+----
+
+*Test File Example:*
+
+[source,wokelang]
+----
+test "consent system blocks without permission" {
+ #care on;
+
+ remember result = only if okay "file.read" {
+ // Should fail without grant
+ readFile("test.txt")
+ };
+
+ expect result to be Oops("Permission denied");
+}
+
+test "worker executes concurrently" {
+ remember start = now();
+ spawn worker {
+ sleep(100);
+ };
+ remember elapsed = now() - start;
+ expect elapsed < 50; // Worker runs in background
+}
+----
+
+*Why Critical:* - Consent system is safety-critical - Regression testing
+essential - CI/CD integration
+
+*Deliverable:* `+woke test+` command
+
+'''''
+
+==== 4. Documentation Generator 📚
+
+*Impact:* API docs, onboarding *Effort:* 1 week
+
+*Features:* - Auto-generate docs from code - Function documentation
+extraction - Stdlib reference - Examples/tutorials - HTML/PDF output
+
+*Implementation:*
+
+[source,rust]
+----
+// src/doc.rs
+pub struct DocGenerator {
+ // Extract doc comments from AST
+ // Generate stdlib reference
+ // Cross-reference functions
+ // Export to HTML/Markdown
+}
+----
+
+*Doc Comment Syntax:*
+
+[source,wokelang]
+----
+##
+# Validates a file path before reading.
+#
+# @param path - File path to validate
+# @returns Okay(path) if valid, Oops(error) otherwise
+# @example
+# remember result = validatePath("data.txt");
+# match result {
+# Okay(p) -> print(p),
+# Oops(e) -> print(e)
+# }
+##
+to validatePath(path: String) -> Result {
+ // ...
+}
+----
+
+*Why Critical:* - Stdlib docs needed - Code sharing requires
+documentation - Onboarding new users
+
+*Deliverable:* `+woke doc+` command
+
+'''''
+
+==== 5. Profiler & Benchmarking ⚡
+
+*Impact:* Performance optimization *Effort:* 1 week
+
+*Features:* - Function execution time - Module call profiling - Worker
+thread latency - Memory usage - Hotspot detection - Flame graphs
+
+*Implementation:*
+
+[source,rust]
+----
+// src/profiler.rs
+pub struct Profiler {
+ // Instrument evaluation
+ // Measure time per function
+ // Track call counts
+ // Memory allocation tracking
+ // Export flamegraph.svg
+}
+----
+
+*Why Critical:* - Need performance baseline - Identify bottlenecks -
+Worker overhead measurement
+
+*Deliverable:* `+woke profile program.woke+`
+
+'''''
+
+=== Medium Priority (Quality of Life)
+
+==== 6. Static Analyzer 🔍
+
+*Impact:* Code quality, bug prevention *Effort:* 1-2 weeks
+
+*Features Beyond Linter:* - Dead code detection - Unreachable code
+branches - Unused imports - Constant propagation analysis - Capability
+leak detection - Security vulnerability scanning
+
+*Example Checks:*
+
+[source,wokelang]
+----
+# Warning: Function 'never_called' is unused
+to never_called() {
+ print("Hello");
+}
+
+# Warning: Unreachable code after 'give back'
+to example() {
+ give back 42;
+ print("This never runs"); // Unreachable
+}
+
+# Error: Capability escape detected
+to leaked_capability() {
+ only if okay "file.write" {
+ // Capability should not escape consent block
+ give back writeFile; // Error
+ }
+}
+----
+
+*Deliverable:* `+woke analyze program.woke+`
+
+'''''
+
+==== 7. Package Manager 📦
+
+*Impact:* Code reuse, ecosystem *Effort:* 2-3 weeks
+
+*Features:* - Package library publishing - Dependency resolution -
+Version management - Standard library versioning - Local/remote package
+registry
+
+*Package Manifest:*
+
+[source,nickel]
+----
+# wokelang.ncl
+{
+ name = "acme-utils",
+ version = "1.0.0",
+ dependencies = {
+ std = "^0.2.0",
+ http = "^1.5.0"
+ },
+ files = [
+ "src/main.woke",
+ "src/utils.woke"
+ ]
+}
+----
+
+*Commands:*
+
+[source,bash]
+----
+woke pkg init
+woke pkg install http
+woke pkg publish
+woke pkg search validation
+----
+
+*Deliverable:* `+woke pkg+` subcommand
+
+'''''
+
+==== 8. Syntax Highlighting Definitions 🎨
+
+*Impact:* Editor support *Effort:* 2-3 days
+
+*Targets:* - VSCode/VSCodium (TextMate grammar) - Vim/Neovim (vim syntax
+file) - Emacs (major mode) - Sublime Text - Kate/KWrite - GitHub/GitLab
+(linguist)
+
+*Files to Create:*
+
+....
+syntax/
+├── wokelang.tmLanguage.json # VSCode/Sublime
+├── wokelang.vim # Vim/Neovim
+├── wokelang-mode.el # Emacs
+└── wokelang.xml # Kate
+....
+
+*Deliverable:* Editor plugin packages
+
+'''''
+
+==== 9. Error Reporter & Diagnostics 🚨
+
+*Impact:* Developer experience *Effort:* 1 week
+
+*Features:* - Colorized error messages - Source context (line + context)
+- Suggestions for fixes - Error codes (E0001, E0002, etc.) - Related
+information - Help text
+
+*Example:*
+
+....
+error[E0042]: undefined variable 'nam'
+ --> hello.woke:12:3
+ |
+12 | print(nam);
+ | ^^^ not found in this scope
+ |
+help: a variable with a similar name exists
+ |
+12 | print(name);
+ | ~~~~
+
+error[E0053]: permission denied for capability 'file.read'
+ --> app.woke:7:5
+ |
+7 | remember data = readFile("secrets.txt");
+ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ requires 'file.read' permission
+ |
+help: wrap in consent block
+ |
+7 | only if okay "file.read" {
+8 | remember data = readFile("secrets.txt");
+9 | }
+ |
+....
+
+*Deliverable:* Enhanced error messages throughout
+
+'''''
+
+==== 10. Code Completion Engine 🔮
+
+*Impact:* IDE productivity *Effort:* 1 week
+
+*Features:* - Function suggestions - Variable name completion - Snippet
+expansion - Context-aware suggestions - Template insertion
+
+*Completions:*
+
+....
+to m| → to myFunction() {
+ |
+ | }
+
+only if | → only if okay "permission" {
+ |
+ | }
+
+spawn w| → spawn worker {
+ |
+ | }
+....
+
+*Deliverable:* LSP `+textDocument/completion+` impl
+
+'''''
+
+=== Low Priority (Advanced Features)
+
+==== 11. Refactoring Tools ♻️
+
+*Impact:* Code maintenance *Effort:* 2 weeks
+
+*Features:* - Extract function (from code) - Inline constant - Rename
+variable/function (safe) - Move to module - Extract module - Change
+signature
+
+*Deliverable:* LSP code actions
+
+'''''
+
+==== 12. Formal Verification Integration 🔢
+
+*Impact:* Safety guarantees *Effort:* 3-4 weeks
+
+*Current:* Idris2 ABI proofs in src/abi/ *Proposed:* Full verification
+of WokeLang programs
+
+[source,wokelang]
+----
+## @verified
+# Ensures array access is in bounds
+to safeGet(arr: [Int], idx: Int) -> Result {
+ if idx >= 0 and idx < length(arr) {
+ give back Okay(arr[idx]);
+ } else {
+ give back Oops("Index out of bounds");
+ }
+}
+----
+
+*Deliverable:* `+woke verify+` command
+
+'''''
+
+==== 13. Package Repository 🏛️
+
+*Impact:* Ecosystem growth *Effort:* 4-6 weeks (infrastructure + UI)
+
+*Features:* - Web UI (search, browse) - REST API - Authentication -
+Package versioning - Download statistics - Documentation hosting
+
+*Stack:* - Deno + Oak (web framework) - PostgreSQL database - S3/Spaces
+for storage - CloudFlare CDN
+
+*URL:* `+https://packages.wokelang.org+`
+
+*Deliverable:* Full package registry service
+
+'''''
+
+==== 14. WASM Target 🌐
+
+*Impact:* Browser execution *Effort:* 2-3 weeks
+
+*Goal:* Compile WokeLang → WebAssembly
+
+*Use Cases:* - WokeLang playground in browser - Client-side execution -
+Embedded in web apps - Edge computing (Cloudflare Workers)
+
+*Implementation:*
+
+[source,bash]
+----
+woke compile --target wasm program.woke -o program.wasm
+----
+
+*Deliverable:* WASM backend for compiler
+
+'''''
+
+==== 15. Multi-language FFI 🔌
+
+*Impact:* External integration *Effort:* 2 weeks
+
+*Current:* Zig FFI in ffi/zig/ *Proposed:* Call any language from
+WokeLang
+
+[source,wokelang]
+----
+# Call Rust function
+extern rust "libcrypto.so" fn hash_sha256(data: String) -> String;
+
+# Call Zig function
+extern zig "libmath.so" fn fast_sqrt(x: Float) -> Float;
+
+to main() {
+ remember result = hash_sha256("hello");
+ print(result);
+}
+----
+
+*Why Deferred:* - Security concerns (capability enforcement) - ABI
+complexity - Sandboxing needed
+
+*Deliverable:* `+extern+` keyword support
+
+'''''
+
+=== Implementation Priority Matrix
+
+[cols=",,,,",options="header",]
+|===
+|Tool |Impact |Effort |Priority |When
+|LSP |Very High |High |1 |Phase 4
+|Debugger |High |Medium |2 |Phase 4
+|Testing Framework |Very High |Low |3 |Phase 3
+|Profiler |Medium |Low |4 |Phase 4
+|Doc Generator |Medium |Low |5 |Phase 4
+|Static Analyzer |Medium |Medium |6 |Phase 5
+|Syntax Highlighting |High |Very Low |7 |Phase 3
+|Error Reporter |Medium |Low |8 |Phase 4
+|Package Manager |High |High |9 |Phase 5
+|Code Completion |Medium |Low |10 |Phase 4 (via LSP)
+|Refactoring |Low |Medium |11 |Phase 6
+|Formal Verification |Medium |High |12 |Phase 6
+|Package Repository |Low |Very High |13 |Phase 7
+|WASM Target |Medium |Medium |14 |Phase 6
+|Multi-language FFI |Medium |Medium |15 |Phase 6
+|===
+
+'''''
+
+=== Recommended Next Steps
+
+*Phase 3 (Current):* Quality & Core Features - Complete stdlib
+integration - Record field access - Comprehensive testing
+
+*Phase 4 (Next):* Developer Tools 1. *Syntax highlighting* (2-3 days) ←
+Quick win 2. *Testing framework* (1 week) ← Essential 3. *LSP server*
+(2-3 weeks) ← Game changer 4. *Debugger* (1-2 weeks) 5. *Profiler* (1
+week) 6. *Doc generator* (1 week)
+
+*Phase 5:* Quality & Ecosystem - Static analyzer - Package manager -
+Error reporter enhancements
+
+*Phase 6:* Advanced Features - Formal verification expansion -
+Refactoring tools - WASM target - Multi-language FFI
+
+*Phase 7:* Infrastructure - Package registry (web service) - Community
+platform
+
+'''''
+
+=== Estimated Timeline
+
+*Complete Toolchain (Production-Grade):* 12-16 weeks
+
+* Phase 3: Core Features (1-2 weeks) ✅ Nearly complete
+* Phase 4: Dev Tools (6-8 weeks)
+* Phase 5: Quality (3-4 weeks)
+* Phase 6: Advanced (2-3 weeks)
+* Phase 7: Infrastructure (when needed)
+
+*MVP Toolchain:* 8 weeks (Phases 3-4 only)
+
+'''''
+
+=== Comparison with Phronesis
+
+Both WokeLang and Phronesis need similar toolchain components:
+
+[width="100%",cols="30%,25%,28%,17%",options="header",]
+|===
+|Component |WokeLang |Phronesis |Notes
+|*Core Language* |✅ Complete |✅ Complete |Both have working
+interpreters
+
+|*LSP* |❌ Missing |❌ Missing |Highest priority for both
+
+|*Debugger* |❌ Missing |❌ Missing |Essential dev tool
+
+|*Testing Framework* |⚠️ Partial |❌ Missing |WokeLang has examples
+
+|*Profiler* |❌ Missing |❌ Missing |Performance tuning
+
+|*Doc Generator* |❌ Missing |❌ Missing |User onboarding
+
+|*Package Manager* |❌ Missing |❌ Missing |Ecosystem growth
+
+|*Syntax Highlighting* |⚠️ Partial |❌ Missing |Quick wins available
+|===
+
+*Convergence Strategy:* Both languages can share tooling approaches and
+learn from each other’s implementations.
+
+'''''
+
+=== Community Contributions Welcome
+
+Lower priority items ideal for contributors: - Syntax highlighting
+definitions - Editor plugins - Documentation examples - Standard library
+functions - Testing WokeLang programs
+
+High-skill contributions: - LSP implementation - Debugger - WASM backend
+- Formal verification
+
+'''''
+
+*Current Status:* 85% complete (core language) *With full toolchain:*
+100% complete (production-ready language)
+
+*Maintainer:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk *Date:*
+2026-02-01 *License:* MPL-2.0
diff --git a/TOOLCHAIN-WISHLIST.md b/TOOLCHAIN-WISHLIST.md
deleted file mode 100644
index e1c1ee4..0000000
--- a/TOOLCHAIN-WISHLIST.md
+++ /dev/null
@@ -1,638 +0,0 @@
-
-// SPDX-License-Identifier: CC-BY-SA-4.0
-// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
-
-# WokeLang Toolchain Wishlist
-## Missing Components for Production-Grade Language
-
-**Current Status:** Core language complete (85% overall)
-
-**Existing Tools:** ✅
-- Lexer, Parser, AST
-- Type System (Hindley-Milner inference)
-- Interpreter (tree-walking)
-- Bytecode VM + Compiler
-- REPL (interactive mode)
-- CLI (`woke run/typecheck/lint/parse/tokenize`)
-- Consent/Capability System (runtime enforcement)
-- Worker System (basic concurrency)
-- Standard Library (partial integration)
-- Examples/Demos
-
----
-
-## High Priority (Production Essentials)
-
-### 1. Language Server Protocol (LSP) 📡
-**Impact:** IDE integration, developer experience
-**Effort:** 2-3 weeks
-
-**Features:**
-- Go to definition
-- Find references
-- Hover documentation
-- Auto-completion
-- Inline diagnostics (errors/warnings)
-- Code actions (quick fixes)
-- Rename symbol
-- Signature help
-
-**Implementation:**
-```rust
-// src/lsp/server.rs
-pub struct LspServer {
- // JSON-RPC server
- // textDocument/didOpen, didChange, didSave
- // textDocument/completion
- // textDocument/hover
- // textDocument/definition
- // textDocument/references
- // textDocument/formatting
-}
-```
-
-**Why Critical:**
-- VSCode/Neovim/Emacs integration
-- Real-time error checking
-- Autocomplete for stdlib functions
-- Standard for modern languages
-
-**Deliverable:** `woke lsp` command
-
----
-
-### 2. Debugger 🐛
-**Impact:** Program development, troubleshooting
-**Effort:** 1-2 weeks
-
-**Features:**
-- Breakpoints in WokeLang code
-- Step-through execution
-- Variable inspection
-- Watch expressions
-- Call stack
-- Worker thread debugging
-
-**Implementation:**
-```rust
-// src/debugger.rs
-pub struct Debugger {
- // Instrument AST with breakpoints
- // Step-by-step evaluation
- // State inspection at each step
- // Integration with existing interpreter
-}
-```
-
-**Why Critical:**
-- Complex programs hard to debug
-- Worker concurrency needs investigation
-- Consent flow debugging
-
-**Deliverable:** `woke debug program.woke`
-
----
-
-### 3. Testing Framework 🧪
-**Impact:** Code reliability, CI/CD
-**Effort:** 1 week
-
-**Features:**
-- Unit tests for WokeLang code
-- Property-based testing
-- Consent scenario testing
-- Worker concurrency tests
-- Coverage reporting
-
-**Implementation:**
-```rust
-// src/test_framework.rs
-pub struct TestFramework {
- // Test macro expansion
- // Assertion functions
- // Test runner
- // Coverage analysis
-}
-```
-
-**Test File Example:**
-```wokelang
-test "consent system blocks without permission" {
- #care on;
-
- remember result = only if okay "file.read" {
- // Should fail without grant
- readFile("test.txt")
- };
-
- expect result to be Oops("Permission denied");
-}
-
-test "worker executes concurrently" {
- remember start = now();
- spawn worker {
- sleep(100);
- };
- remember elapsed = now() - start;
- expect elapsed < 50; // Worker runs in background
-}
-```
-
-**Why Critical:**
-- Consent system is safety-critical
-- Regression testing essential
-- CI/CD integration
-
-**Deliverable:** `woke test` command
-
----
-
-### 4. Documentation Generator 📚
-**Impact:** API docs, onboarding
-**Effort:** 1 week
-
-**Features:**
-- Auto-generate docs from code
-- Function documentation extraction
-- Stdlib reference
-- Examples/tutorials
-- HTML/PDF output
-
-**Implementation:**
-```rust
-// src/doc.rs
-pub struct DocGenerator {
- // Extract doc comments from AST
- // Generate stdlib reference
- // Cross-reference functions
- // Export to HTML/Markdown
-}
-```
-
-**Doc Comment Syntax:**
-```wokelang
-##
-# Validates a file path before reading.
-#
-# @param path - File path to validate
-# @returns Okay(path) if valid, Oops(error) otherwise
-# @example
-# remember result = validatePath("data.txt");
-# match result {
-# Okay(p) -> print(p),
-# Oops(e) -> print(e)
-# }
-##
-to validatePath(path: String) -> Result {
- // ...
-}
-```
-
-**Why Critical:**
-- Stdlib docs needed
-- Code sharing requires documentation
-- Onboarding new users
-
-**Deliverable:** `woke doc` command
-
----
-
-### 5. Profiler & Benchmarking ⚡
-**Impact:** Performance optimization
-**Effort:** 1 week
-
-**Features:**
-- Function execution time
-- Module call profiling
-- Worker thread latency
-- Memory usage
-- Hotspot detection
-- Flame graphs
-
-**Implementation:**
-```rust
-// src/profiler.rs
-pub struct Profiler {
- // Instrument evaluation
- // Measure time per function
- // Track call counts
- // Memory allocation tracking
- // Export flamegraph.svg
-}
-```
-
-**Why Critical:**
-- Need performance baseline
-- Identify bottlenecks
-- Worker overhead measurement
-
-**Deliverable:** `woke profile program.woke`
-
----
-
-## Medium Priority (Quality of Life)
-
-### 6. Static Analyzer 🔍
-**Impact:** Code quality, bug prevention
-**Effort:** 1-2 weeks
-
-**Features Beyond Linter:**
-- Dead code detection
-- Unreachable code branches
-- Unused imports
-- Constant propagation analysis
-- Capability leak detection
-- Security vulnerability scanning
-
-**Example Checks:**
-```wokelang
-# Warning: Function 'never_called' is unused
-to never_called() {
- print("Hello");
-}
-
-# Warning: Unreachable code after 'give back'
-to example() {
- give back 42;
- print("This never runs"); // Unreachable
-}
-
-# Error: Capability escape detected
-to leaked_capability() {
- only if okay "file.write" {
- // Capability should not escape consent block
- give back writeFile; // Error
- }
-}
-```
-
-**Deliverable:** `woke analyze program.woke`
-
----
-
-### 7. Package Manager 📦
-**Impact:** Code reuse, ecosystem
-**Effort:** 2-3 weeks
-
-**Features:**
-- Package library publishing
-- Dependency resolution
-- Version management
-- Standard library versioning
-- Local/remote package registry
-
-**Package Manifest:**
-```nickel
-# wokelang.ncl
-{
- name = "acme-utils",
- version = "1.0.0",
- dependencies = {
- std = "^0.2.0",
- http = "^1.5.0"
- },
- files = [
- "src/main.woke",
- "src/utils.woke"
- ]
-}
-```
-
-**Commands:**
-```bash
-woke pkg init
-woke pkg install http
-woke pkg publish
-woke pkg search validation
-```
-
-**Deliverable:** `woke pkg` subcommand
-
----
-
-### 8. Syntax Highlighting Definitions 🎨
-**Impact:** Editor support
-**Effort:** 2-3 days
-
-**Targets:**
-- VSCode/VSCodium (TextMate grammar)
-- Vim/Neovim (vim syntax file)
-- Emacs (major mode)
-- Sublime Text
-- Kate/KWrite
-- GitHub/GitLab (linguist)
-
-**Files to Create:**
-```
-syntax/
-├── wokelang.tmLanguage.json # VSCode/Sublime
-├── wokelang.vim # Vim/Neovim
-├── wokelang-mode.el # Emacs
-└── wokelang.xml # Kate
-```
-
-**Deliverable:** Editor plugin packages
-
----
-
-### 9. Error Reporter & Diagnostics 🚨
-**Impact:** Developer experience
-**Effort:** 1 week
-
-**Features:**
-- Colorized error messages
-- Source context (line + context)
-- Suggestions for fixes
-- Error codes (E0001, E0002, etc.)
-- Related information
-- Help text
-
-**Example:**
-```
-error[E0042]: undefined variable 'nam'
- --> hello.woke:12:3
- |
-12 | print(nam);
- | ^^^ not found in this scope
- |
-help: a variable with a similar name exists
- |
-12 | print(name);
- | ~~~~
-
-error[E0053]: permission denied for capability 'file.read'
- --> app.woke:7:5
- |
-7 | remember data = readFile("secrets.txt");
- | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ requires 'file.read' permission
- |
-help: wrap in consent block
- |
-7 | only if okay "file.read" {
-8 | remember data = readFile("secrets.txt");
-9 | }
- |
-```
-
-**Deliverable:** Enhanced error messages throughout
-
----
-
-### 10. Code Completion Engine 🔮
-**Impact:** IDE productivity
-**Effort:** 1 week
-
-**Features:**
-- Function suggestions
-- Variable name completion
-- Snippet expansion
-- Context-aware suggestions
-- Template insertion
-
-**Completions:**
-```
-to m| → to myFunction() {
- |
- | }
-
-only if | → only if okay "permission" {
- |
- | }
-
-spawn w| → spawn worker {
- |
- | }
-```
-
-**Deliverable:** LSP `textDocument/completion` impl
-
----
-
-## Low Priority (Advanced Features)
-
-### 11. Refactoring Tools ♻️
-**Impact:** Code maintenance
-**Effort:** 2 weeks
-
-**Features:**
-- Extract function (from code)
-- Inline constant
-- Rename variable/function (safe)
-- Move to module
-- Extract module
-- Change signature
-
-**Deliverable:** LSP code actions
-
----
-
-### 12. Formal Verification Integration 🔢
-**Impact:** Safety guarantees
-**Effort:** 3-4 weeks
-
-**Current:** Idris2 ABI proofs in src/abi/
-**Proposed:** Full verification of WokeLang programs
-
-```wokelang
-## @verified
-# Ensures array access is in bounds
-to safeGet(arr: [Int], idx: Int) -> Result {
- if idx >= 0 and idx < length(arr) {
- give back Okay(arr[idx]);
- } else {
- give back Oops("Index out of bounds");
- }
-}
-```
-
-**Deliverable:** `woke verify` command
-
----
-
-### 13. Package Repository 🏛️
-**Impact:** Ecosystem growth
-**Effort:** 4-6 weeks (infrastructure + UI)
-
-**Features:**
-- Web UI (search, browse)
-- REST API
-- Authentication
-- Package versioning
-- Download statistics
-- Documentation hosting
-
-**Stack:**
-- Deno + Oak (web framework)
-- PostgreSQL database
-- S3/Spaces for storage
-- CloudFlare CDN
-
-**URL:** `https://packages.wokelang.org`
-
-**Deliverable:** Full package registry service
-
----
-
-### 14. WASM Target 🌐
-**Impact:** Browser execution
-**Effort:** 2-3 weeks
-
-**Goal:** Compile WokeLang → WebAssembly
-
-**Use Cases:**
-- WokeLang playground in browser
-- Client-side execution
-- Embedded in web apps
-- Edge computing (Cloudflare Workers)
-
-**Implementation:**
-```bash
-woke compile --target wasm program.woke -o program.wasm
-```
-
-**Deliverable:** WASM backend for compiler
-
----
-
-### 15. Multi-language FFI 🔌
-**Impact:** External integration
-**Effort:** 2 weeks
-
-**Current:** Zig FFI in ffi/zig/
-**Proposed:** Call any language from WokeLang
-
-```wokelang
-# Call Rust function
-extern rust "libcrypto.so" fn hash_sha256(data: String) -> String;
-
-# Call Zig function
-extern zig "libmath.so" fn fast_sqrt(x: Float) -> Float;
-
-to main() {
- remember result = hash_sha256("hello");
- print(result);
-}
-```
-
-**Why Deferred:**
-- Security concerns (capability enforcement)
-- ABI complexity
-- Sandboxing needed
-
-**Deliverable:** `extern` keyword support
-
----
-
-## Implementation Priority Matrix
-
-| Tool | Impact | Effort | Priority | When |
-|------|--------|--------|----------|------|
-| LSP | Very High | High | 1 | Phase 4 |
-| Debugger | High | Medium | 2 | Phase 4 |
-| Testing Framework | Very High | Low | 3 | Phase 3 |
-| Profiler | Medium | Low | 4 | Phase 4 |
-| Doc Generator | Medium | Low | 5 | Phase 4 |
-| Static Analyzer | Medium | Medium | 6 | Phase 5 |
-| Syntax Highlighting | High | Very Low | 7 | Phase 3 |
-| Error Reporter | Medium | Low | 8 | Phase 4 |
-| Package Manager | High | High | 9 | Phase 5 |
-| Code Completion | Medium | Low | 10 | Phase 4 (via LSP) |
-| Refactoring | Low | Medium | 11 | Phase 6 |
-| Formal Verification | Medium | High | 12 | Phase 6 |
-| Package Repository | Low | Very High | 13 | Phase 7 |
-| WASM Target | Medium | Medium | 14 | Phase 6 |
-| Multi-language FFI | Medium | Medium | 15 | Phase 6 |
-
----
-
-## Recommended Next Steps
-
-**Phase 3 (Current):** Quality & Core Features
-- Complete stdlib integration
-- Record field access
-- Comprehensive testing
-
-**Phase 4 (Next):** Developer Tools
-1. **Syntax highlighting** (2-3 days) ← Quick win
-2. **Testing framework** (1 week) ← Essential
-3. **LSP server** (2-3 weeks) ← Game changer
-4. **Debugger** (1-2 weeks)
-5. **Profiler** (1 week)
-6. **Doc generator** (1 week)
-
-**Phase 5:** Quality & Ecosystem
-- Static analyzer
-- Package manager
-- Error reporter enhancements
-
-**Phase 6:** Advanced Features
-- Formal verification expansion
-- Refactoring tools
-- WASM target
-- Multi-language FFI
-
-**Phase 7:** Infrastructure
-- Package registry (web service)
-- Community platform
-
----
-
-## Estimated Timeline
-
-**Complete Toolchain (Production-Grade):** 12-16 weeks
-
-- Phase 3: Core Features (1-2 weeks) ✅ Nearly complete
-- Phase 4: Dev Tools (6-8 weeks)
-- Phase 5: Quality (3-4 weeks)
-- Phase 6: Advanced (2-3 weeks)
-- Phase 7: Infrastructure (when needed)
-
-**MVP Toolchain:** 8 weeks (Phases 3-4 only)
-
----
-
-## Comparison with Phronesis
-
-Both WokeLang and Phronesis need similar toolchain components:
-
-| Component | WokeLang | Phronesis | Notes |
-|-----------|----------|-----------|-------|
-| **Core Language** | ✅ Complete | ✅ Complete | Both have working interpreters |
-| **LSP** | ❌ Missing | ❌ Missing | Highest priority for both |
-| **Debugger** | ❌ Missing | ❌ Missing | Essential dev tool |
-| **Testing Framework** | ⚠️ Partial | ❌ Missing | WokeLang has examples |
-| **Profiler** | ❌ Missing | ❌ Missing | Performance tuning |
-| **Doc Generator** | ❌ Missing | ❌ Missing | User onboarding |
-| **Package Manager** | ❌ Missing | ❌ Missing | Ecosystem growth |
-| **Syntax Highlighting** | ⚠️ Partial | ❌ Missing | Quick wins available |
-
-**Convergence Strategy:** Both languages can share tooling approaches and learn from each other's implementations.
-
----
-
-## Community Contributions Welcome
-
-Lower priority items ideal for contributors:
-- Syntax highlighting definitions
-- Editor plugins
-- Documentation examples
-- Standard library functions
-- Testing WokeLang programs
-
-High-skill contributions:
-- LSP implementation
-- Debugger
-- WASM backend
-- Formal verification
-
----
-
-**Current Status:** 85% complete (core language)
-**With full toolchain:** 100% complete (production-ready language)
-
-**Maintainer:** Jonathan D.A. Jewell
-**Date:** 2026-02-01
-**License:** MPL-2.0
diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc
similarity index 81%
rename from TOPOLOGY.md
rename to TOPOLOGY.adoc
index 27c44a3..2aedf40 100644
--- a/TOPOLOGY.md
+++ b/TOPOLOGY.adoc
@@ -1,15 +1,8 @@
-
-
-
+== Wokelang — Project Topology
-# Wokelang — Project Topology
+=== System Architecture
-## System Architecture
-
-```
+....
┌─────────────────────────────────────────┐
│ USER / INPUT │
└───────────────────┬─────────────────────┘
@@ -27,10 +20,11 @@ Copyright (c) Jonathan D.A. Jewell
┌─────────────────────────────────────────┐
│ DATA / STORAGE │
└─────────────────────────────────────────┘
-```
-## Completion Dashboard
+....
+
+=== Completion Dashboard
-```
+....
COMPONENT STATUS NOTES
───────────────────────────────── ────────────────── ─────────────────────────────────
CORE LOGIC
@@ -45,25 +39,26 @@ INFRASTRUCTURE
─────────────────────────────────────────────────────────────────────────────
OVERALL: ███████░░░ ~70% Functional prototype / MVP
-```
+....
-## Key Dependencies
+=== Key Dependencies
-```
+....
User ──────► CLI / Interface ──────► Core Logic
│
▼
Data / State
-```
+....
-## Update Protocol
+=== Update Protocol
This file is maintained by both humans and AI agents. When updating:
-1. **After completing a component**: Change its bar and percentage
-2. **After adding a component**: Add a new row in the appropriate section
-3. **After architectural changes**: Update the ASCII diagram
-4. **Date**: Update the `Last updated` comment at the top of this file
+[arabic]
+. *After completing a component*: Change its bar and percentage
+. *After adding a component*: Add a new row in the appropriate section
+. *After architectural changes*: Update the ASCII diagram
+. *Date*: Update the `+Last updated+` comment at the top of this file
-Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
-Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).
+Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide.
+Percentages: 0%, 10%, 20%, … 100% (in 10% increments).
diff --git a/docs/NEXT-CLAUDE-PROMPT.adoc b/docs/NEXT-CLAUDE-PROMPT.adoc
new file mode 100644
index 0000000..906e121
--- /dev/null
+++ b/docs/NEXT-CLAUDE-PROMPT.adoc
@@ -0,0 +1,70 @@
+== WokeLang — handoff prompt for the next Claude
+
+Paste the block below into a fresh Claude Code session working on
+`+hyperpolymath/wokelang+`. (State as of 2026-06-19 — see
+`+AFFIRMATION.adoc+`.)
+
+'''''
+
+You are continuing work on *WokeLang*, a consent-driven, human-centred
+programming language. Primary implementation is *Rust* (`+src/+`), with
+an *OCaml* reference core (`+core/+`) and formal proofs in *Lean/Coq*
+(`+docs/proofs/verification/+`) and *Idris 2* (`+src/abi/+`). Match the
+interpreter (`+src/interpreter/mod.rs+`) as the reference semantics.
+
+*Read first, in order:* 1. `+AFFIRMATION.adoc+` — the current MUST /
+INTEND / WISH standing (timestamped). 2.
+`+.machine_readable/6a2/STATE.a2ml+` — project state checkpoint. 3.
+`+docs/proofs/verification/AUDIT.md+` — proof state (Lean / Coq /
+Idris). 4. `+PROOF-NEEDS.md+`, `+TEST-NEEDS.md+`,
+`+TOOLCHAIN-WISHLIST.md+` — needs and wishes. (Note:
+`+TOOLCHAIN-WISHLIST.md+` is *stale* — LSP, the DAP debugger, and the
+WASM backend already exist; and it says 85% complete while
+`+STATE.a2ml+` says 35%. Reconciling these is itself an open task.)
+
+*Where things stand (2026-06-19):* - *Proofs.* Lean + Coq at parity
+(expression-core type safety + arrays + statement typing) and an Idris
+consent calculus (typing with a handler context + small-step with an
+audit log + `+progress+`). CI-gated (`+lean-proofs.yml+`,
+`+coq-proofs.yml+`), `+sorry+`/axiom-free. - *Bytecode VM*
+(`+src/vm/+`). Now runs the core language: Result types, records,
+indexing, control flow, *consent enforcement under `+#care+`*
+(deny-by-default), and *closures with upvalue capture*. 188 lib tests
+green. It went from crashing on most programs to running the core
+language this session (PRs #92–#94).
+
+*Best next steps (near-horizon, mostly independent — pick one):* - _VM →
+real compilation target:_ - *Interpreter↔VM parity harness:* run each
+`+conformance/*.woke+` and `+examples/*.woke+` through both the
+interpreter and `+vm::run_vm+`, assert equal results, CI-gate it.
+(Highest-value correctness mechanism.) - *`+.wbc+` bytecode
+serialization:* `+woke compile -o x.wbc+` cannot write a loadable file
+yet (`+src/main.rs+` says "`not yet implemented`"); add serde round-trip
+so `+woke run-vm x.wbc+` loads it. - *Consent grant-sources:* seed the
+VM’s `+granted+` set (in `+src/vm/machine.rs+`) from `+superpower+`
+declarations so `+#care+` programs can actually grant capabilities
+(currently deny-by-default). - *Worker statements on the VM* (the 5
+concurrency forms — needs a VM channel/scheduler model). - *By-reference
++ multi-level closure capture* (current capture is by-value,
+single-level). - _Proofs:_ *float arithmetic* variants; *open-term
+expression preservation* (the prerequisite for statement _dynamic_
+safety); decide the *eval ↔ spec correspondence* question (PROOF-NEEDS
+#2) with the maintainer. - _Docs:_ *reconcile* `+README.adoc+` /
+`+EXPLAINME.adoc+` / `+TOOLCHAIN-WISHLIST.md+` to reality and fix the
+35%-vs-85% completion contradiction.
+
+*Conventions & CI gates:* - Develop on the branch you are told to; push
+and open a *draft PR*. - Gates include *Build Check*
+(`+cargo fmt --check+` +
+`+cargo clippy --lib --bins -- -D warnings+`), *Build + E2E (Rust +
+OCaml)*, *lean-proofs*, *coq-proofs*. *Run `+cargo fmt+` +
+`+cargo clippy --lib --bins -- -D warnings+` locally before pushing* —
+Build Check gates on both, and that has bitten past sessions. - Language
+policy (`+.claude/CLAUDE.md+`): Rust / OCaml / Lean / Coq / Idris as
+present; no Go / Python / TypeScript; `+Containerfile+`, not
+`+Dockerfile+`. - Keep proofs `+sorry+`/axiom-free; pin each headline
+theorem the way `+AUDIT.md+` describes.
+
+Tell me which item to take, or propose one and go.
+
+'''''
diff --git a/docs/NEXT-CLAUDE-PROMPT.md b/docs/NEXT-CLAUDE-PROMPT.md
deleted file mode 100644
index 37511bd..0000000
--- a/docs/NEXT-CLAUDE-PROMPT.md
+++ /dev/null
@@ -1,72 +0,0 @@
-
-# WokeLang — handoff prompt for the next Claude
-
-Paste the block below into a fresh Claude Code session working on
-`hyperpolymath/wokelang`. (State as of 2026-06-19 — see `AFFIRMATION.adoc`.)
-
----
-
-You are continuing work on **WokeLang**, a consent-driven, human-centred
-programming language. Primary implementation is **Rust** (`src/`), with an
-**OCaml** reference core (`core/`) and formal proofs in **Lean/Coq**
-(`docs/proofs/verification/`) and **Idris 2** (`src/abi/`). Match the
-interpreter (`src/interpreter/mod.rs`) as the reference semantics.
-
-**Read first, in order:**
-1. `AFFIRMATION.adoc` — the current MUST / INTEND / WISH standing (timestamped).
-2. `.machine_readable/6a2/STATE.a2ml` — project state checkpoint.
-3. `docs/proofs/verification/AUDIT.md` — proof state (Lean / Coq / Idris).
-4. `PROOF-NEEDS.md`, `TEST-NEEDS.md`, `TOOLCHAIN-WISHLIST.md` — needs and wishes.
- (Note: `TOOLCHAIN-WISHLIST.md` is **stale** — LSP, the DAP debugger, and the
- WASM backend already exist; and it says 85% complete while `STATE.a2ml` says
- 35%. Reconciling these is itself an open task.)
-
-**Where things stand (2026-06-19):**
-- **Proofs.** Lean + Coq at parity (expression-core type safety + arrays +
- statement typing) and an Idris consent calculus (typing with a handler
- context + small-step with an audit log + `progress`). CI-gated
- (`lean-proofs.yml`, `coq-proofs.yml`), `sorry`/axiom-free.
-- **Bytecode VM** (`src/vm/`). Now runs the core language: Result types,
- records, indexing, control flow, **consent enforcement under `#care`**
- (deny-by-default), and **closures with upvalue capture**. 188 lib tests green.
- It went from crashing on most programs to running the core language this
- session (PRs #92–#94).
-
-**Best next steps (near-horizon, mostly independent — pick one):**
-- *VM → real compilation target:*
- - **Interpreter↔VM parity harness:** run each `conformance/*.woke` and
- `examples/*.woke` through both the interpreter and `vm::run_vm`, assert
- equal results, CI-gate it. (Highest-value correctness mechanism.)
- - **`.wbc` bytecode serialization:** `woke compile -o x.wbc` cannot write a
- loadable file yet (`src/main.rs` says "not yet implemented"); add serde
- round-trip so `woke run-vm x.wbc` loads it.
- - **Consent grant-sources:** seed the VM's `granted` set (in `src/vm/machine.rs`)
- from `superpower` declarations so `#care` programs can actually grant
- capabilities (currently deny-by-default).
- - **Worker statements on the VM** (the 5 concurrency forms — needs a VM
- channel/scheduler model).
- - **By-reference + multi-level closure capture** (current capture is by-value,
- single-level).
-- *Proofs:* **float arithmetic** variants; **open-term expression preservation**
- (the prerequisite for statement *dynamic* safety); decide the **eval ↔ spec
- correspondence** question (PROOF-NEEDS #2) with the maintainer.
-- *Docs:* **reconcile** `README.adoc` / `EXPLAINME.adoc` / `TOOLCHAIN-WISHLIST.md`
- to reality and fix the 35%-vs-85% completion contradiction.
-
-**Conventions & CI gates:**
-- Develop on the branch you are told to; push and open a **draft PR**.
-- Gates include **Build Check** (`cargo fmt --check` + `cargo clippy --lib --bins
- -- -D warnings`), **Build + E2E (Rust + OCaml)**, **lean-proofs**, **coq-proofs**.
- **Run `cargo fmt` + `cargo clippy --lib --bins -- -D warnings` locally before
- pushing** — Build Check gates on both, and that has bitten past sessions.
-- Language policy (`.claude/CLAUDE.md`): Rust / OCaml / Lean / Coq / Idris as
- present; no Go / Python / TypeScript; `Containerfile`, not `Dockerfile`.
-- Keep proofs `sorry`/axiom-free; pin each headline theorem the way `AUDIT.md`
- describes.
-
-Tell me which item to take, or propose one and go.
-
----
diff --git a/docs/PROVEN.adoc b/docs/PROVEN.adoc
new file mode 100644
index 0000000..e678d5a
--- /dev/null
+++ b/docs/PROVEN.adoc
@@ -0,0 +1,94 @@
+== Proven Integration
+
+WokeLang uses https://github.com/hyperpolymath/proven[proven] for
+formally verified operations where safety is critical.
+
+=== What is proven?
+
+proven is an Idris2 library providing mathematically proven safe
+operations: - *Cannot crash* - Dependent types prove correctness -
+*Totality checking* - All code paths guaranteed to terminate - *90+
+modules* - Comprehensive formally verified functionality - *89 language
+bindings* - FFI via Zig C ABI
+
+=== Architecture
+
+....
+WokeLang (Rust)
+ ↓
+Rust Bindings
+ ↓
+Zig FFI Bridge
+ ↓
+Idris2 proven Library ← MATHEMATICAL PROOFS
+....
+
+=== Integration Points
+
+==== Current
+
+WokeLang currently uses proven for: - (To be determined based on
+safety-critical needs)
+
+==== Planned
+
+Potential proven integration for: - *File I/O* - Proven-safe file
+operations with capability checks - *String operations* - Bounds-checked
+string manipulation - *Collection operations* - Verified data structure
+operations - *Parser combinators* - Provably correct parsing
+
+=== Using proven in WokeLang
+
+==== Setup
+
+[arabic]
+. Ensure Idris2 is installed (see `+.tool-versions+`)
+. Clone proven:
++
+[source,bash]
+----
+git clone https://github.com/hyperpolymath/proven
+cd proven
+make install
+----
+. Link WokeLang to proven bindings:
++
+[source,bash]
+----
+cd wokelang
+# Add proven-rust bindings to Cargo.toml
+----
+
+==== Example
+
+[source,rust]
+----
+// Use proven-safe string operations
+use proven_rust::string::SafeString;
+
+let s = SafeString::new("Hello").unwrap();
+let sub = s.substring(0, 5); // Mathematically proven not to panic
+----
+
+=== Badge
+
+When WokeLang uses proven modules, add the "`Idris Inside`" badge to
+README:
+
+[source,adoc]
+----
+image:https://img.shields.io/badge/Idris-Inside-blueviolet?style=flat[Idris Inside]
+----
+
+=== Performance Note
+
+proven adds FFI overhead for maximum safety. Use for: - ✓
+Safety-critical operations (file I/O, parsing user input) - ✓ Security
+boundaries (capability checks, permission validation) - ✗ Hot loops or
+performance-critical paths
+
+=== References
+
+* proven repo: https://github.com/hyperpolymath/proven
+* Idris2 docs: https://idris2.readthedocs.io
+* Zig FFI: /var$REPOS_DIR/proven/ffi/zig/
diff --git a/docs/PROVEN.md b/docs/PROVEN.md
deleted file mode 100644
index 7b8f5d2..0000000
--- a/docs/PROVEN.md
+++ /dev/null
@@ -1,91 +0,0 @@
-
-# Proven Integration
-
-WokeLang uses [proven](https://github.com/hyperpolymath/proven) for formally verified operations where safety is critical.
-
-## What is proven?
-
-proven is an Idris2 library providing mathematically proven safe operations:
-- **Cannot crash** - Dependent types prove correctness
-- **Totality checking** - All code paths guaranteed to terminate
-- **90+ modules** - Comprehensive formally verified functionality
-- **89 language bindings** - FFI via Zig C ABI
-
-## Architecture
-
-```
-WokeLang (Rust)
- ↓
-Rust Bindings
- ↓
-Zig FFI Bridge
- ↓
-Idris2 proven Library ← MATHEMATICAL PROOFS
-```
-
-## Integration Points
-
-### Current
-
-WokeLang currently uses proven for:
-- (To be determined based on safety-critical needs)
-
-### Planned
-
-Potential proven integration for:
-- **File I/O** - Proven-safe file operations with capability checks
-- **String operations** - Bounds-checked string manipulation
-- **Collection operations** - Verified data structure operations
-- **Parser combinators** - Provably correct parsing
-
-## Using proven in WokeLang
-
-### Setup
-
-1. Ensure Idris2 is installed (see `.tool-versions`)
-2. Clone proven:
- ```bash
- git clone https://github.com/hyperpolymath/proven
- cd proven
- make install
- ```
-
-3. Link WokeLang to proven bindings:
- ```bash
- cd wokelang
- # Add proven-rust bindings to Cargo.toml
- ```
-
-### Example
-
-```rust
-// Use proven-safe string operations
-use proven_rust::string::SafeString;
-
-let s = SafeString::new("Hello").unwrap();
-let sub = s.substring(0, 5); // Mathematically proven not to panic
-```
-
-## Badge
-
-When WokeLang uses proven modules, add the "Idris Inside" badge to README:
-
-```adoc
-image:https://img.shields.io/badge/Idris-Inside-blueviolet?style=flat[Idris Inside]
-```
-
-## Performance Note
-
-proven adds FFI overhead for maximum safety. Use for:
-- ✓ Safety-critical operations (file I/O, parsing user input)
-- ✓ Security boundaries (capability checks, permission validation)
-- ✗ Hot loops or performance-critical paths
-
-## References
-
-- proven repo: https://github.com/hyperpolymath/proven
-- Idris2 docs: https://idris2.readthedocs.io
-- Zig FFI: /var$REPOS_DIR/proven/ffi/zig/
diff --git a/docs/ROADMAP.adoc b/docs/ROADMAP.adoc
new file mode 100644
index 0000000..3d2c93f
--- /dev/null
+++ b/docs/ROADMAP.adoc
@@ -0,0 +1,331 @@
+== WokeLang Roadmap
+
+____
+A human-centered, consent-driven programming language
+____
+
+=== Vision
+
+WokeLang aims to be a programming language that prioritizes: - *Human
+readability* over machine optimization - *Explicit consent* for
+sensitive operations - *Gratitude and attribution* as first-class
+concepts - *Emotional context* through emote annotations - *Safety by
+default* with gentle error handling
+
+'''''
+
+=== Phase 1: Foundation (Current) ✅
+
+==== Core Language
+
+* [x] EBNF grammar specification
+* [x] Lexer with logos
+* [x] Recursive descent parser
+* [x] Complete AST types
+* [x] Tree-walking interpreter
+
+==== Basic Features
+
+* [x] Functions with `+to+`/`+give back+`
+* [x] Variables with `+remember+`
+* [x] Conditionals with `+when+`/`+otherwise+`
+* [x] Loops with `+repeat...times+`
+* [x] Basic types: Int, Float, String, Bool, Array
+
+==== Tooling
+
+* [x] CLI (`+woke+` command)
+* [x] Interactive REPL
+* [x] WASM compilation
+* [x] C/Zig FFI
+
+'''''
+
+=== Phase 2: Language Completeness (Q1 2026)
+
+==== Type System
+
+* [ ] Static type inference
+* [ ] Generic types (`+to map[T, U](list: [T], f: T -> U) -> [U]+`)
+* [ ] Union types (`+String | Int+`)
+* [ ] Structural typing for records
+* [ ] Unit types with compile-time checking
+
+==== Pattern Matching
+
+* [ ] Destructuring in `+decide based on+`
+* [ ] Guard clauses
+* [ ] Exhaustiveness checking
+* [ ] Nested patterns
+
+==== Module System
+
+* [ ] Package management (`+woke.toml+`)
+* [ ] Import/export with `+use+`/`+share+`
+* [ ] Namespaces
+* [ ] Circular dependency detection
+
+==== Error Handling
+
+* [ ] Result types (`+Okay[T] | Oops[E]+`)
+* [ ] Error propagation operator (`+?+`)
+* [ ] Stack traces with source locations
+* [ ] Custom error types
+
+'''''
+
+=== Phase 3: Concurrency & Safety (Q2 2026)
+
+==== Worker System
+
+* [ ] True async workers
+* [ ] Message passing between workers
+* [ ] Worker pools
+* [ ] Cancellation tokens
+
+==== Side Quests
+
+* [ ] Background task scheduling
+* [ ] Progress reporting
+* [ ] Resource cleanup
+
+==== Superpowers
+
+* [ ] Capability-based security
+* [ ] Permission inheritance
+* [ ] Audit logging
+* [ ] Sandboxing
+
+==== Consent System
+
+* [ ] Persistent consent storage
+* [ ] Scoped permissions
+* [ ] Consent revocation
+* [ ] Consent UI integration
+
+'''''
+
+=== Phase 4: Standard Library (Q3 2026)
+
+==== Core Modules
+
+* [ ] `+std.io+` - File I/O with consent
+* [ ] `+std.net+` - Networking with consent
+* [ ] `+std.json+` - JSON parsing/generation
+* [ ] `+std.time+` - Date/time handling
+* [ ] `+std.math+` - Mathematical functions
+* [ ] `+std.text+` - String manipulation
+* [ ] `+std.collections+` - Data structures
+
+==== Consent-Aware Modules
+
+* [ ] `+std.fs+` - Filesystem with permission checks
+* [ ] `+std.http+` - HTTP client with URL consent
+* [ ] `+std.crypto+` - Cryptography primitives
+* [ ] `+std.env+` - Environment variables
+
+==== Unit System
+
+* [ ] `+std.units.si+` - SI units
+* [ ] `+std.units.imperial+` - Imperial units
+* [ ] `+std.units.currency+` - Currency types
+* [ ] Automatic unit conversion
+* [ ] Dimensional analysis
+
+'''''
+
+=== Phase 5: Compiler & Performance (Q4 2026)
+
+==== WASM Target
+
+* [ ] Full WASM feature support
+* [ ] WASI integration
+* [ ] Memory management
+* [ ] String handling in WASM
+* [ ] Array operations
+* [ ] Exception handling
+
+==== Native Compilation
+
+* [ ] LLVM backend
+* [ ] Native binaries
+* [ ] Cross-compilation
+* [ ] Link-time optimization
+
+==== Optimizations
+
+* [ ] Constant folding
+* [ ] Dead code elimination
+* [ ] Inlining
+* [ ] Tail call optimization
+* [ ] Loop unrolling
+
+'''''
+
+=== Phase 6: Tooling & Ecosystem (2027)
+
+==== IDE Support
+
+* [ ] VS Code extension
+** Syntax highlighting
+** Error diagnostics
+** Auto-completion
+** Go to definition
+** Rename refactoring
+* [ ] Language Server Protocol (LSP)
+* [ ] Tree-sitter grammar
+* [ ] Vim/Neovim plugin
+* [ ] JetBrains plugin
+
+==== Package Manager
+
+* [ ] `+woke pkg+` command
+* [ ] Central package registry
+* [ ] Version resolution
+* [ ] Lock files
+* [ ] Security auditing
+
+==== Testing
+
+* [ ] Built-in test framework
+* [ ] Property-based testing
+* [ ] Mocking support
+* [ ] Coverage reporting
+* [ ] Benchmark suite
+
+==== Documentation
+
+* [ ] `+woke doc+` generator
+* [ ] Inline documentation
+* [ ] Example extraction
+* [ ] API reference generation
+
+'''''
+
+=== Phase 7: Frameworks (2027+)
+
+==== Web Framework (WokeWeb)
+
+* [ ] HTTP server
+* [ ] Routing with consent
+* [ ] Middleware system
+* [ ] Template engine
+* [ ] WebSocket support
+* [ ] Static file serving
+
+==== CLI Framework (WokeCLI)
+
+* [ ] Argument parsing
+* [ ] Interactive prompts
+* [ ] Progress bars
+* [ ] Color output
+* [ ] Configuration files
+
+==== GUI Framework (WokeUI)
+
+* [ ] Cross-platform windowing
+* [ ] Declarative UI
+* [ ] Event handling
+* [ ] Theming
+* [ ] Accessibility
+
+==== Data Framework (WokeData)
+
+* [ ] Database abstraction
+* [ ] Query builder
+* [ ] Migrations
+* [ ] Connection pooling
+* [ ] Consent-aware queries
+
+'''''
+
+=== Technical Milestones
+
+==== Lexer Enhancements
+
+[cols=",,",options="header",]
+|===
+|Feature |Status |Version
+|Unicode identifiers |Planned |0.3.0
+|Heredoc strings |Planned |0.3.0
+|Raw strings |Planned |0.3.0
+|String interpolation |Planned |0.4.0
+|Custom operators |Planned |0.5.0
+|===
+
+==== Parser Enhancements
+
+[cols=",,",options="header",]
+|===
+|Feature |Status |Version
+|Error recovery |Planned |0.3.0
+|Incremental parsing |Planned |0.5.0
+|Macro expansion |Planned |0.6.0
+|Custom syntax |Planned |1.0.0
+|===
+
+==== Compiler Targets
+
+[cols=",,",options="header",]
+|===
+|Target |Status |Version
+|Tree-walking interpreter |✅ Done |0.1.0
+|WASM (basic) |✅ Done |0.1.0
+|WASM (full) |Planned |0.4.0
+|LLVM IR |Planned |0.6.0
+|Native (x86_64) |Planned |0.7.0
+|Native (ARM64) |Planned |0.8.0
+|===
+
+==== REPL Features
+
+[cols=",,",options="header",]
+|===
+|Feature |Status |Version
+|Basic evaluation |✅ Done |0.1.0
+|History |✅ Done |0.1.0
+|Multi-line input |Planned |0.2.0
+|Tab completion |Planned |0.3.0
+|Syntax highlighting |Planned |0.4.0
+|Debugger integration |Planned |0.6.0
+|===
+
+'''''
+
+=== Version Timeline
+
+....
+2024 Q4 v0.1.0 Foundation release (completed)
+2026 Q1 v0.2.0 Type system, modules
+2026 Q2 v0.3.0 Concurrency, safety
+2026 Q3 v0.4.0 Standard library
+2026 Q4 v0.5.0 Optimizing compiler
+2027 Q1 v0.6.0 IDE support, LSP
+2027 Q2 v0.7.0 Package manager
+2027 Q3 v0.8.0 Web framework
+2027 Q4 v1.0.0 Stable release
+....
+
+'''''
+
+=== Contributing
+
+See link:../CONTRIBUTING.md[CONTRIBUTING.md] for how to get involved.
+
+==== Priority Areas
+
+[arabic]
+. Standard library implementations
+. Documentation and examples
+. IDE tooling
+. Performance optimization
+. Security auditing
+
+'''''
+
+=== Links
+
+* link:spec/language.md[Language Specification]
+* link:wiki/Home.md[Wiki Home]
+* link:api/README.md[API Reference]
+* link:tutorials/README.md[Tutorials]
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
deleted file mode 100644
index 90a2f2e..0000000
--- a/docs/ROADMAP.md
+++ /dev/null
@@ -1,295 +0,0 @@
-
-# WokeLang Roadmap
-
-> A human-centered, consent-driven programming language
-
-## Vision
-
-WokeLang aims to be a programming language that prioritizes:
-- **Human readability** over machine optimization
-- **Explicit consent** for sensitive operations
-- **Gratitude and attribution** as first-class concepts
-- **Emotional context** through emote annotations
-- **Safety by default** with gentle error handling
-
----
-
-## Phase 1: Foundation (Current) ✅
-
-### Core Language
-- [x] EBNF grammar specification
-- [x] Lexer with logos
-- [x] Recursive descent parser
-- [x] Complete AST types
-- [x] Tree-walking interpreter
-
-### Basic Features
-- [x] Functions with `to`/`give back`
-- [x] Variables with `remember`
-- [x] Conditionals with `when`/`otherwise`
-- [x] Loops with `repeat...times`
-- [x] Basic types: Int, Float, String, Bool, Array
-
-### Tooling
-- [x] CLI (`woke` command)
-- [x] Interactive REPL
-- [x] WASM compilation
-- [x] C/Zig FFI
-
----
-
-## Phase 2: Language Completeness (Q1 2026)
-
-### Type System
-- [ ] Static type inference
-- [ ] Generic types (`to map[T, U](list: [T], f: T -> U) -> [U]`)
-- [ ] Union types (`String | Int`)
-- [ ] Structural typing for records
-- [ ] Unit types with compile-time checking
-
-### Pattern Matching
-- [ ] Destructuring in `decide based on`
-- [ ] Guard clauses
-- [ ] Exhaustiveness checking
-- [ ] Nested patterns
-
-### Module System
-- [ ] Package management (`woke.toml`)
-- [ ] Import/export with `use`/`share`
-- [ ] Namespaces
-- [ ] Circular dependency detection
-
-### Error Handling
-- [ ] Result types (`Okay[T] | Oops[E]`)
-- [ ] Error propagation operator (`?`)
-- [ ] Stack traces with source locations
-- [ ] Custom error types
-
----
-
-## Phase 3: Concurrency & Safety (Q2 2026)
-
-### Worker System
-- [ ] True async workers
-- [ ] Message passing between workers
-- [ ] Worker pools
-- [ ] Cancellation tokens
-
-### Side Quests
-- [ ] Background task scheduling
-- [ ] Progress reporting
-- [ ] Resource cleanup
-
-### Superpowers
-- [ ] Capability-based security
-- [ ] Permission inheritance
-- [ ] Audit logging
-- [ ] Sandboxing
-
-### Consent System
-- [ ] Persistent consent storage
-- [ ] Scoped permissions
-- [ ] Consent revocation
-- [ ] Consent UI integration
-
----
-
-## Phase 4: Standard Library (Q3 2026)
-
-### Core Modules
-- [ ] `std.io` - File I/O with consent
-- [ ] `std.net` - Networking with consent
-- [ ] `std.json` - JSON parsing/generation
-- [ ] `std.time` - Date/time handling
-- [ ] `std.math` - Mathematical functions
-- [ ] `std.text` - String manipulation
-- [ ] `std.collections` - Data structures
-
-### Consent-Aware Modules
-- [ ] `std.fs` - Filesystem with permission checks
-- [ ] `std.http` - HTTP client with URL consent
-- [ ] `std.crypto` - Cryptography primitives
-- [ ] `std.env` - Environment variables
-
-### Unit System
-- [ ] `std.units.si` - SI units
-- [ ] `std.units.imperial` - Imperial units
-- [ ] `std.units.currency` - Currency types
-- [ ] Automatic unit conversion
-- [ ] Dimensional analysis
-
----
-
-## Phase 5: Compiler & Performance (Q4 2026)
-
-### WASM Target
-- [ ] Full WASM feature support
-- [ ] WASI integration
-- [ ] Memory management
-- [ ] String handling in WASM
-- [ ] Array operations
-- [ ] Exception handling
-
-### Native Compilation
-- [ ] LLVM backend
-- [ ] Native binaries
-- [ ] Cross-compilation
-- [ ] Link-time optimization
-
-### Optimizations
-- [ ] Constant folding
-- [ ] Dead code elimination
-- [ ] Inlining
-- [ ] Tail call optimization
-- [ ] Loop unrolling
-
----
-
-## Phase 6: Tooling & Ecosystem (2027)
-
-### IDE Support
-- [ ] VS Code extension
- - Syntax highlighting
- - Error diagnostics
- - Auto-completion
- - Go to definition
- - Rename refactoring
-- [ ] Language Server Protocol (LSP)
-- [ ] Tree-sitter grammar
-- [ ] Vim/Neovim plugin
-- [ ] JetBrains plugin
-
-### Package Manager
-- [ ] `woke pkg` command
-- [ ] Central package registry
-- [ ] Version resolution
-- [ ] Lock files
-- [ ] Security auditing
-
-### Testing
-- [ ] Built-in test framework
-- [ ] Property-based testing
-- [ ] Mocking support
-- [ ] Coverage reporting
-- [ ] Benchmark suite
-
-### Documentation
-- [ ] `woke doc` generator
-- [ ] Inline documentation
-- [ ] Example extraction
-- [ ] API reference generation
-
----
-
-## Phase 7: Frameworks (2027+)
-
-### Web Framework (WokeWeb)
-- [ ] HTTP server
-- [ ] Routing with consent
-- [ ] Middleware system
-- [ ] Template engine
-- [ ] WebSocket support
-- [ ] Static file serving
-
-### CLI Framework (WokeCLI)
-- [ ] Argument parsing
-- [ ] Interactive prompts
-- [ ] Progress bars
-- [ ] Color output
-- [ ] Configuration files
-
-### GUI Framework (WokeUI)
-- [ ] Cross-platform windowing
-- [ ] Declarative UI
-- [ ] Event handling
-- [ ] Theming
-- [ ] Accessibility
-
-### Data Framework (WokeData)
-- [ ] Database abstraction
-- [ ] Query builder
-- [ ] Migrations
-- [ ] Connection pooling
-- [ ] Consent-aware queries
-
----
-
-## Technical Milestones
-
-### Lexer Enhancements
-| Feature | Status | Version |
-|---------|--------|---------|
-| Unicode identifiers | Planned | 0.3.0 |
-| Heredoc strings | Planned | 0.3.0 |
-| Raw strings | Planned | 0.3.0 |
-| String interpolation | Planned | 0.4.0 |
-| Custom operators | Planned | 0.5.0 |
-
-### Parser Enhancements
-| Feature | Status | Version |
-|---------|--------|---------|
-| Error recovery | Planned | 0.3.0 |
-| Incremental parsing | Planned | 0.5.0 |
-| Macro expansion | Planned | 0.6.0 |
-| Custom syntax | Planned | 1.0.0 |
-
-### Compiler Targets
-| Target | Status | Version |
-|--------|--------|---------|
-| Tree-walking interpreter | ✅ Done | 0.1.0 |
-| WASM (basic) | ✅ Done | 0.1.0 |
-| WASM (full) | Planned | 0.4.0 |
-| LLVM IR | Planned | 0.6.0 |
-| Native (x86_64) | Planned | 0.7.0 |
-| Native (ARM64) | Planned | 0.8.0 |
-
-### REPL Features
-| Feature | Status | Version |
-|---------|--------|---------|
-| Basic evaluation | ✅ Done | 0.1.0 |
-| History | ✅ Done | 0.1.0 |
-| Multi-line input | Planned | 0.2.0 |
-| Tab completion | Planned | 0.3.0 |
-| Syntax highlighting | Planned | 0.4.0 |
-| Debugger integration | Planned | 0.6.0 |
-
----
-
-## Version Timeline
-
-```
-2024 Q4 v0.1.0 Foundation release (completed)
-2026 Q1 v0.2.0 Type system, modules
-2026 Q2 v0.3.0 Concurrency, safety
-2026 Q3 v0.4.0 Standard library
-2026 Q4 v0.5.0 Optimizing compiler
-2027 Q1 v0.6.0 IDE support, LSP
-2027 Q2 v0.7.0 Package manager
-2027 Q3 v0.8.0 Web framework
-2027 Q4 v1.0.0 Stable release
-```
-
----
-
-## Contributing
-
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to get involved.
-
-### Priority Areas
-1. Standard library implementations
-2. Documentation and examples
-3. IDE tooling
-4. Performance optimization
-5. Security auditing
-
----
-
-## Links
-
-- [Language Specification](spec/language.md)
-- [Wiki Home](wiki/Home.md)
-- [API Reference](api/README.md)
-- [Tutorials](tutorials/README.md)
diff --git a/docs/core/INDEX.adoc b/docs/core/INDEX.adoc
new file mode 100644
index 0000000..67bb48b
--- /dev/null
+++ b/docs/core/INDEX.adoc
@@ -0,0 +1,76 @@
+== WokeLang Documentation Index
+
+This index separates *core* documentation (required for the OCaml
+implementation) from *optional* documentation (for
+quarantined/experimental features).
+
+=== Core Documentation
+
+Essential documentation for the OCaml-based WokeLang implementation:
+
+[width="100%",cols="44%,56%",options="header",]
+|===
+|Document |Description
+|SETUP.md |OCaml-only setup instructions
+|../grammar.ebnf |Complete EBNF grammar specification
+|SPEC.core.scm |Core language semantics (consent + units)
+|===
+
+==== Core Language Features
+
+* *Consent gates* (`+only if okay+`) - Explicit permission for sensitive
+operations
+* *Units of measure* (`+measured in+`) - Type-safe physical quantities
+* *Gratitude blocks* (`+thanks to+`) - Attribution in code
+* *Natural control flow* (`+when+`/`+otherwise+`, `+repeat times+`)
+* *Safe error handling* (`+attempt safely+`/`+or reassure+`)
+* *Emote annotations* (`+@enthusiastic+`) - Emotional context
+
+=== Optional Documentation
+
+Documentation for quarantined/experimental features:
+
+[cols=",,",options="header",]
+|===
+|Document |Description |Status
+|WASM build |Browser/Node.js compilation |Quarantined
+|Rust implementation |Alternative implementation |Quarantined
+|Vyper FFI |Blockchain integration |Quarantined
+|===
+
+=== Conformance Corpus
+
+Test cases focusing on core semantics:
+
+==== Consent Semantics
+
+* `+test/consent_grant.wl+` - Consent is requested and granted
+* `+test/consent_deny.wl+` - Consent is denied
+* `+test/consent_scope.wl+` - Consent scoping rules
+
+==== Units Semantics
+
+* `+test/units_basic.wl+` - Basic unit operations
+* `+test/units_mismatch.wl+` - Unit mismatch errors (deterministic)
+* `+test/units_conversion.wl+` - Unit conversion (future)
+
+==== Error Diagnostics
+
+* All error messages must be deterministic
+* Line/column information must be accurate
+* Error messages should be helpful and human-centered
+
+=== Implementation Reference
+
+The authoritative reference implementation is:
+
+....
+core/
+├── ast.ml # AST definitions
+├── lexer.mll # Lexer
+├── parser.mly # Parser
+├── eval.ml # Evaluator
+└── main.ml # CLI
+....
+
+This OCaml implementation is the source of truth for language semantics.
diff --git a/docs/core/INDEX.md b/docs/core/INDEX.md
deleted file mode 100644
index 7f21b1c..0000000
--- a/docs/core/INDEX.md
+++ /dev/null
@@ -1,74 +0,0 @@
-
-# WokeLang Documentation Index
-
-This index separates **core** documentation (required for the OCaml implementation)
-from **optional** documentation (for quarantined/experimental features).
-
-## Core Documentation
-
-Essential documentation for the OCaml-based WokeLang implementation:
-
-| Document | Description |
-|----------|-------------|
-| [SETUP.md](SETUP.md) | OCaml-only setup instructions |
-| [../grammar.ebnf](../grammar.ebnf) | Complete EBNF grammar specification |
-| [SPEC.core.scm](SPEC.core.scm) | Core language semantics (consent + units) |
-
-### Core Language Features
-
-- **Consent gates** (`only if okay`) - Explicit permission for sensitive operations
-- **Units of measure** (`measured in`) - Type-safe physical quantities
-- **Gratitude blocks** (`thanks to`) - Attribution in code
-- **Natural control flow** (`when`/`otherwise`, `repeat times`)
-- **Safe error handling** (`attempt safely`/`or reassure`)
-- **Emote annotations** (`@enthusiastic`) - Emotional context
-
-## Optional Documentation
-
-Documentation for quarantined/experimental features:
-
-| Document | Description | Status |
-|----------|-------------|--------|
-| WASM build | Browser/Node.js compilation | Quarantined |
-| Rust implementation | Alternative implementation | Quarantined |
-| Vyper FFI | Blockchain integration | Quarantined |
-
-## Conformance Corpus
-
-Test cases focusing on core semantics:
-
-### Consent Semantics
-
-- `test/consent_grant.wl` - Consent is requested and granted
-- `test/consent_deny.wl` - Consent is denied
-- `test/consent_scope.wl` - Consent scoping rules
-
-### Units Semantics
-
-- `test/units_basic.wl` - Basic unit operations
-- `test/units_mismatch.wl` - Unit mismatch errors (deterministic)
-- `test/units_conversion.wl` - Unit conversion (future)
-
-### Error Diagnostics
-
-- All error messages must be deterministic
-- Line/column information must be accurate
-- Error messages should be helpful and human-centered
-
-## Implementation Reference
-
-The authoritative reference implementation is:
-
-```
-core/
-├── ast.ml # AST definitions
-├── lexer.mll # Lexer
-├── parser.mly # Parser
-├── eval.ml # Evaluator
-└── main.ml # CLI
-```
-
-This OCaml implementation is the source of truth for language semantics.
diff --git a/docs/core/SETUP.md b/docs/core/SETUP.adoc
similarity index 56%
rename from docs/core/SETUP.md
rename to docs/core/SETUP.adoc
index 96218c9..34f1c70 100644
--- a/docs/core/SETUP.md
+++ b/docs/core/SETUP.adoc
@@ -1,21 +1,19 @@
-
-# WokeLang OCaml Core Setup
+== WokeLang OCaml Core Setup
-This document describes the minimal OCaml-only setup path for building and
-running WokeLang core. No Rust, WASM, or Vyper dependencies are required.
+This document describes the minimal OCaml-only setup path for building
+and running WokeLang core. No Rust, WASM, or Vyper dependencies are
+required.
-## Prerequisites
+=== Prerequisites
-- OCaml 5.0+ (install via opam)
-- dune 3.0+ (install via opam)
-- menhir (install via opam)
+* OCaml 5.0+ (install via opam)
+* dune 3.0+ (install via opam)
+* menhir (install via opam)
-### Quick Install (Linux/macOS)
+==== Quick Install (Linux/macOS)
-```bash
+[source,bash]
+----
# Install opam if not present
bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh)"
@@ -27,55 +25,61 @@ eval $(opam env)
opam switch create 5.1.0
eval $(opam env)
opam install dune menhir
-```
+----
-### Guix Install
+==== Guix Install
-```bash
+[source,bash]
+----
guix install ocaml ocaml-dune ocaml-menhir
-```
+----
-### Nix Install
+==== Nix Install
-```bash
+[source,bash]
+----
nix-shell -p ocaml dune_3 ocamlPackages.menhir
-```
+----
-## Building
+=== Building
From the repository root:
-```bash
+[source,bash]
+----
# Build the core interpreter
dune build
# Install locally
dune install --prefix=.local
-```
+----
-## Running
+=== Running
-### Run a WokeLang file
+==== Run a WokeLang file
-```bash
+[source,bash]
+----
dune exec -- wokelang examples/hello_world.wl
-```
+----
-### Run tests
+==== Run tests
-```bash
+[source,bash]
+----
dune test
-```
+----
-### Smoke test (golden path)
+==== Smoke test (golden path)
-```bash
+[source,bash]
+----
dune test && dune exec -- wokelang examples/hello_world.wl
-```
+----
-## Project Structure (Core)
+=== Project Structure (Core)
-```
+....
wokelang/
├── core/ # OCaml core implementation
│ ├── dune # Build configuration
@@ -93,54 +97,60 @@ wokelang/
└── docs/
└── core/
└── SETUP.md # This file
-```
+....
-## Success Criteria
+=== Success Criteria
The core is considered working when:
-1. `dune build` completes without errors
-2. `dune test` passes all tests
-3. `dune exec -- wokelang examples/hello_world.wl` runs successfully
-4. Invalid programs produce deterministic error messages
+[arabic]
+. `+dune build+` completes without errors
+. `+dune test+` passes all tests
+. `+dune exec -- wokelang examples/hello_world.wl+` runs successfully
+. Invalid programs produce deterministic error messages
-## Optional Components (Quarantined)
+=== Optional Components (Quarantined)
The following components are NOT required for core functionality:
-- **Rust implementation** (`src/`, `Cargo.toml`) - Alternative implementation
-- **WASM build** - Browser/Node.js target
-- **Vyper FFI** - Blockchain integration
+* *Rust implementation* (`+src/+`, `+Cargo.toml+`) - Alternative
+implementation
+* *WASM build* - Browser/Node.js target
+* *Vyper FFI* - Blockchain integration
These remain in the repository but are not part of the core build path.
-## Troubleshooting
+=== Troubleshooting
-### "menhir not found"
+==== "`menhir not found`"
-```bash
+[source,bash]
+----
opam install menhir
eval $(opam env)
-```
+----
-### "OCaml version too old"
+==== "`OCaml version too old`"
-```bash
+[source,bash]
+----
opam switch create 5.1.0
eval $(opam env)
-```
+----
-### "dune not found"
+==== "`dune not found`"
-```bash
+[source,bash]
+----
opam install dune
eval $(opam env)
-```
+----
-## Next Steps
+=== Next Steps
After setting up the core:
-1. Try the examples in `examples/`
-2. Read the language specification in `grammar/wokelang.ebnf`
-3. Explore the formal semantics in `docs/proofs/`
+[arabic]
+. Try the examples in `+examples/+`
+. Read the language specification in `+grammar/wokelang.ebnf+`
+. Explore the formal semantics in `+docs/proofs/+`
diff --git a/docs/proofs/README.adoc b/docs/proofs/README.adoc
new file mode 100644
index 0000000..a0775a7
--- /dev/null
+++ b/docs/proofs/README.adoc
@@ -0,0 +1,90 @@
+== WokeLang Formal Proofs and Academic Documentation
+
+This directory contains formal mathematical proofs, specifications, and
+academic documentation for the WokeLang programming language.
+
+=== Directory Structure
+
+....
+proofs/
+├── formal-semantics/ # Operational and denotational semantics
+├── type-theory/ # Type system proofs and foundations
+├── security/ # Capability-based security proofs
+├── compiler/ # Compiler correctness proofs
+├── complexity/ # Complexity analysis
+├── concurrency/ # Worker system and concurrency proofs
+├── verification/ # Formal verification specifications (Coq/Lean)
+└── papers/ # White papers and design documents
+....
+
+=== Quick Reference
+
+[width="100%",cols="34%,25%,41%",options="header",]
+|===
+|Document |Status |Description
+|link:formal-semantics/operational-semantics.md[Operational Semantics]
+|Complete |Big-step and small-step semantics
+
+|link:formal-semantics/denotational-semantics.md[Denotational Semantics]
+|Complete |Mathematical meaning of programs
+
+|link:type-theory/type-safety.md[Type Safety] |Complete |Progress and
+preservation theorems
+
+|link:type-theory/hindley-milner.md[Hindley-Milner] |Complete |Type
+inference algorithm
+
+|link:security/capability-proofs.md[Capability Security] |Complete
+|Security properties
+
+|link:security/consent-model.md[Consent Model] |Complete |Formal consent
+semantics
+
+|link:compiler/semantic-preservation.md[Compiler Correctness] |Complete
+|Correctness of compilation
+
+|link:complexity/complexity-analysis.md[Complexity] |Complete |Time and
+space bounds
+
+|link:concurrency/worker-safety.md[Concurrency] |Complete |Worker system
+proofs
+
+|link:verification/WokeLang.v[Coq Specification] |Stub |Formal
+verification in Coq
+
+|link:papers/language-design-whitepaper.md[Language Design] |Complete
+|Design rationale
+|===
+
+=== Mathematical Notation
+
+Throughout these documents, we use standard notation:
+
+* `+Γ+` (Gamma): Type environment
+* `+⊢+` (turnstile): Type judgment
+* `+→+` (arrow): Function type / reduction
+* `+⇓+` (double arrow): Big-step evaluation
+* `+⊆+` (subset): Subtyping / capability subsumption
+* `+∀+` (forall): Universal quantification
+* `+∃+` (exists): Existential quantification
+* `+⊥+` (bottom): Error / undefined
+* `+⊤+` (top): Unit / any type
+
+=== Citation
+
+If using these proofs in academic work:
+
+[source,bibtex]
+----
+@misc{wokelang2025,
+ title={WokeLang: A Consent-Driven, Human-Centered Programming Language},
+ author={WokeLang Contributors},
+ year={2025},
+ howpublished={\url{https://github.com/hyperpolymath/wokelang}}
+}
+----
+
+=== License
+
+This documentation is released under the same license as WokeLang (see
+repository root).
diff --git a/docs/proofs/README.md b/docs/proofs/README.md
deleted file mode 100644
index b4d8d55..0000000
--- a/docs/proofs/README.md
+++ /dev/null
@@ -1,68 +0,0 @@
-
-# WokeLang Formal Proofs and Academic Documentation
-
-This directory contains formal mathematical proofs, specifications, and academic documentation for the WokeLang programming language.
-
-## Directory Structure
-
-```
-proofs/
-├── formal-semantics/ # Operational and denotational semantics
-├── type-theory/ # Type system proofs and foundations
-├── security/ # Capability-based security proofs
-├── compiler/ # Compiler correctness proofs
-├── complexity/ # Complexity analysis
-├── concurrency/ # Worker system and concurrency proofs
-├── verification/ # Formal verification specifications (Coq/Lean)
-└── papers/ # White papers and design documents
-```
-
-## Quick Reference
-
-| Document | Status | Description |
-|----------|--------|-------------|
-| [Operational Semantics](formal-semantics/operational-semantics.md) | Complete | Big-step and small-step semantics |
-| [Denotational Semantics](formal-semantics/denotational-semantics.md) | Complete | Mathematical meaning of programs |
-| [Type Safety](type-theory/type-safety.md) | Complete | Progress and preservation theorems |
-| [Hindley-Milner](type-theory/hindley-milner.md) | Complete | Type inference algorithm |
-| [Capability Security](security/capability-proofs.md) | Complete | Security properties |
-| [Consent Model](security/consent-model.md) | Complete | Formal consent semantics |
-| [Compiler Correctness](compiler/semantic-preservation.md) | Complete | Correctness of compilation |
-| [Complexity](complexity/complexity-analysis.md) | Complete | Time and space bounds |
-| [Concurrency](concurrency/worker-safety.md) | Complete | Worker system proofs |
-| [Coq Specification](verification/WokeLang.v) | Stub | Formal verification in Coq |
-| [Language Design](papers/language-design-whitepaper.md) | Complete | Design rationale |
-
-## Mathematical Notation
-
-Throughout these documents, we use standard notation:
-
-- `Γ` (Gamma): Type environment
-- `⊢` (turnstile): Type judgment
-- `→` (arrow): Function type / reduction
-- `⇓` (double arrow): Big-step evaluation
-- `⊆` (subset): Subtyping / capability subsumption
-- `∀` (forall): Universal quantification
-- `∃` (exists): Existential quantification
-- `⊥` (bottom): Error / undefined
-- `⊤` (top): Unit / any type
-
-## Citation
-
-If using these proofs in academic work:
-
-```bibtex
-@misc{wokelang2025,
- title={WokeLang: A Consent-Driven, Human-Centered Programming Language},
- author={WokeLang Contributors},
- year={2025},
- howpublished={\url{https://github.com/hyperpolymath/wokelang}}
-}
-```
-
-## License
-
-This documentation is released under the same license as WokeLang (see repository root).
diff --git a/docs/proofs/VERIFICATION-ROADMAP.adoc b/docs/proofs/VERIFICATION-ROADMAP.adoc
new file mode 100644
index 0000000..f367dce
--- /dev/null
+++ b/docs/proofs/VERIFICATION-ROADMAP.adoc
@@ -0,0 +1,318 @@
+== WokeLang Formal-Verification Roadmap
+
+Scope for taking WokeLang from "`a model of the expression core +
+grammar metatheory is machine-checked`" to "`fully proved.`" Companion
+to link:verification/AUDIT.md[`+verification/AUDIT.md+`],
+link:verification/GRAMMAR-PROOF-INVENTORY.md[`+verification/GRAMMAR-PROOF-INVENTORY.md+`],
+and link:../../PROOF-NEEDS.md[`+../../PROOF-NEEDS.md+`]. Derived from a
+four-part survey of every proof document and the implementation
+(2026-06).
+
+=== The two axes (and the honest reality)
+
+"`Fully proved across its entire extent`" means two very different
+things:
+
+* *Axis 1 — breadth of the _models_:* mechanize every prose proof (type
+inference, semantics, compiler, security, complexity, concurrency) in
+Lean 4 (4.30.0, Mathlib-free, single-file) and/or Coq 8.18.0. Mostly
+tractable; a few items are infeasible without Mathlib.
+* *Axis 2 — depth, _model ↔ real code_:* connect the proofs to the
+actual *~23k-LOC Rust* implementation (plus a divergent ~1.1k-LOC OCaml
+`+core/+`). There is currently *no extraction, no refinement proof, no
+translation validation* in place. The machine-checked proofs cover
+roughly *10–15 %* of the 94-production surface language, and they verify
+*models, not code*.
+
+____
+*Reality check.* Literal "`fully proved against the shipping Rust`" is
+CompCert + RustBelt scale — multiple person-years, research-grade
+tooling that does not exist for this codebase (async / `+tokio+` /
+proc-macros). It is a new research program, not an extension of the
+present work. What _is_ achievable is *"`the language model fully
+proved, plus an empirical bridge to the code.`"*
+____
+
+=== Current baseline (machine-checked, hole-free, CI-gated)
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|File |Covers
+|`+verification/WokeLang.lean+` / `+.v+` |expression-core *type safety*
+(progress, preservation, type-safety, canonical forms, arrays,
+`+Result+`/`+unwrap+` panic); statement *typing + execution* (all nine
+forms — simple + control-flow with faithful lexical block scoping;
+store-typing preservation); consent monotonicity/preservation;
+capability preorder
+
+|`+verification/WokeGrammar.lean+` |verified-parser core (soundness,
+completeness, termination, precedence, determinism)
+
+|`+verification/WokeGrammarStructure.{lean,v}+` |no-left-recursion
+(whole grammar), maximal munch, keyword priority, LL(1)✗/LL(2)✓
+
+|`+verification/WokeGrammar{CFL,Regular,Pumping}.lean+` |CFL closure,
+non-regularity, the CFL pumping lemma, `+aⁿbⁿcⁿ ∉ CFL+`, ∩ non-closure
+|===
+
+=== Fix-first: five spec bugs (each Small, do as the phase is reached)
+
+These are _wrong as written_ and will block the corresponding proofs:
+
+[arabic]
+. *HM `+unify(Int,Float)=promote+`* makes the "`most general unifier`"
+theorems false — model widening as *subtyping*, not unification. (blocks
+Phase 3a)
+. *`+Step+` is non-deterministic* (`+sArrayVal+` overlaps element rules)
+— blocks any determinism proof. (blocks Phase 1c)
+. *Float `+==+` reflexivity* is false on `+NaN+` — the memory-model
+equality claim needs restating (decidable structural eq, or exclude
+floats).
+. *Unbounded `+Int+` vs `+ℤ₆₄+`* — the model uses ℤ; the language is
+64-bit wrapping. Affects arithmetic laws and compiler/WASM correctness.
+(cross-cutting)
+. *Three-way divergence* — Rust, OCaml `+core/+`, and the Lean/Coq
+models disagree on `+Result+`/units/coercions, so "`the impl refines the
+proof`" is currently ill-posed. Resolve by making one model *normative*.
+(blocks Axis 2)
+
+=== Axis 1 — phases (dependency-ordered)
+
+[width="100%",cols="20%,20%,20%,20%,20%",options="header",]
+|===
+|Phase |Deliverable |Effort |Mathlib-free? |Depends on
+|*1. Full type safety* |substitution lemma + `+[T-Call]+`/`+Φ+` +
+indexing → progress/preservation for the full _expression_ language |M
+|yes |core
+
+|*1b. Statement dynamics* |statement execution relation + store-typing
+preservation |L |yes |1
+
+|*1c. Operational metatheory* |fix determinism, add big-step, big↔small
+equivalence |M |yes |bug 2, 1b
+
+|*2a. Capability order* |antisymmetry + `+hasCapability+` satisfaction
+lemmas (+ Coq `+cap_subsumes_trans+`) |S |yes |—
+
+|*2b. Consent state machine* |duration/expiry, protocol completeness +
+determinism + unforgability, isolation |M |yes (excl. IO persistence,
+LTL/CTL) |—
+
+|*2c. Capability state machine* |no-privilege-escalation, confinement,
+revocation, temporal, audit |M |yes |2a
+
+|*3a. HM inference (soundness)* |`+unify+` (well-founded + occurs check)
++ Algorithm W *soundness* |L |yes (hand-rolled `+FTV+`/`+Subst+`) |1,
+bug 1
+
+|*3b. HM completeness* |principal types / most-general |XL |yes but
+large |3a
+
+|*4a. Compiler simulation* |Lean bytecode IR + VM + `+compile+` +
+forward simulation (interpret↔VM) |L |yes |1c
+
+|*4b. Lexer/parser in Lean* |`+tokenize+`/`+parse+` + EBNF conformance
+(beyond current structural facts) |M ea. |yes |—
+
+|*4c. WASM preservation* |WASM-subset semantics + preservation |L |yes
+(partial) |4a
+
+|*5a. Category theory (concrete)* |functor / monad / naturality laws for
+`+Maybe+`/`+Result+`/`+List+`/`+State+` |S–M |yes |—
+
+|*6. Complexity (structural)* |AST-size + `+bytecode ≤ k·AST+` size
+theorems only |L |yes |4a
+
+|*7. Concurrency (scoped)* |interleaving semantics + worker isolation +
+message-non-loss safety |L |yes |1b
+|===
+
+=== Axis 1 — explicitly out of scope / research-grade
+
+* *Denotational adequacy* (`+𝕍 ≅ … + (𝕍→𝕍⊥)+`, fixpoints): recursive
+function-summand fails Lean’s positivity check; needs Scott domain
+theory → XL, likely infeasible single-file/Mathlib-free. Restrict to the
+first-order fragment (M) or descope.
+* *Category-theory headline claims* (CCC, all finite limits/colimits,
+adjunctions, Yoneda, topos): need Mathlib’s `+CategoryTheory+` (policy
+conflict); several are not well-posed about an actual defined category.
+Descope or grant a one-module Mathlib exception.
+* *Complexity asymptotics* (`+O(·)+`, inverse-Ackermann/union-find,
+crate constants): claims about Rust + external crates, not witnessable
+in a model.
+* *Concurrency race/deadlock freedom + CSP trace-equivalence*: evidence
+is Rust ownership / a not-yet-built async runtime — not faithfully
+mechanizable.
+* *Memory model* (use-after-free, double-free, data races, UTF-8,
+atomic-write persistence): Rust/POSIX host properties, _not_
+object-language theorems. Only bounds-safety + equality-relation are
+real (S).
+
+=== Axis 2 — model ↔ implementation
+
+[width="100%",cols="25%,25%,25%,25%",options="header",]
+|===
+|Approach |Guarantee |Effort |Reality
+|*(E) Make one model normative; kill 3-way divergence* |well-posedness
+|M |*Prerequisite* for any bridge being meaningful
+
+|*(A) Differential + property-based testing* |empirical |S–M |*Only
+realistic near-term bridge*; tooling exists (`+proptest+`, `+fuzz/+`,
+`+conformance/+`)
+
+|*(B) Translation validation for the parser* |per-run certificate |L
+|model already half-supports it (renderer inversion)
+
+|*(C) Coq→OCaml extraction of a _new_ reference interpreter* |extracted
+= verified |L |idiomatic, but _replaces_ `+core/eval.ml+` rather than
+validating it
+
+|*(D) Rust refinement (Aeneas/Creusot/Verus), core fragment only* |impl
+⊑ model |XL |research-grade; async/macros out of tool scope
+
+|*Full verified source→WASM compiler* |end-to-end |XL
+(multi-person-year) |CompCert-scale; new project
+|===
+
+=== Recommended target — three tiers
+
+* *Tier 1 — the model is fully proved.* Phases 1, 1b, 1c, 2a–2c, 3a, 4a
+plus the five spec-bug fixes: full type safety, sound type inference, a
+verified compiler simulation, and real security state machines. The
+achievable bulk — all Mathlib-free, extending the hole-free core.
+* *Tier 2 — empirical bridge to the code.* (E) + (A): resolve divergence
+and stand up cross-backend differential / property testing. Real
+confidence the Rust/OCaml code matches the verified model.
+* *Tier 3 — true refinement / verified compilation.* (D) and
+source→WASM: explicitly a research program (multi-person-year). Not a
+committed deliverable.
+
+*First increment* (lowest risk, highest leverage): the five spec-bug
+fixes + *Phase 2a* (capability order, S) + *Phase 1* (full-expression
+type safety via the substitution lemma, M). These extend the existing
+hole-free file directly and unlock Phases 1c / 3a / 4a.
+
+=== Progress
+
+* [x] *Phase 2a (Lean)* — capability partial order
+(`+capSubsumes_antisymm+`, completing `+_refl+`/`+_trans+`) +
+satisfaction lemmas (`+hasCapability_mono+`,
+`+hasCapability_subsumes+`). Coq parity
+(`+cap_subsumes_trans+`/`+_antisymm+`) remains a deliberate follow-up —
+the author left it unproven rather than ship fragile 6×6×6 automation; a
+clean Coq proof wants a `+cap_subsumes+` characterization lemma.
+* [~] *Phase 1 (partial)* — the *Substitution Lemma* (`+subst+` +
+`+subst_preserves_typing+`, type-safety.md Lemma 3.4) is mechanized on
+the hole-free core, by induction on the typing derivation with the
+context generalized (axioms `+propext+`, `+Quot.sound+`). This is the
+prerequisite for `+[T-Call]+`’s preservation case and for Algorithm W
+soundness (3a). _Finding:_ `+[T-Call]+` dynamics here are NOT the
+assumed simple body-substitution — `+Expr.call+` is by name and
+`+TopItem.functionDef+` bodies are *statement lists*, so call reduction
+entangles with statement _execution_ and belongs with *Phase 1b*
+(statement dynamics), not this step. There is also no `+index+`
+constructor, so `+[T-Index]+` requires an AST extension. Roadmap refined
+accordingly.
+* [~] *Phase 1b (foundation)* — *store typing* (`+StoreWellTyped+`)
+bridging the static `+TypeEnv+` and the runtime `+Env+`, with the three
+lemmas the statement-execution preservation proofs rest on:
+`+store_wellTyped_empty+` (empty store types against the empty context),
+`+store_wellTyped_lookup+` (a typed variable resolves to a value of its
+type), and `+store_wellTyped_extend+` (extending context+store in
+lockstep — exactly a `+varDecl+` — preserves store typing). Hole-free
+(axiom `+propext+` only).
+* [~] *Phase 1b (substrate)* — *expression-evaluation invariants under a
+store*, the layer the statement-execution relation sits on:
+`+step_store_invariant+` and `+multiStep_store_invariant+` (expression
+evaluation never mutates `+ρ+` — so a sub-evaluation inside a statement
+can’t disturb the bindings the statement effect then acts on), and
+`+hasType_lit_any+` (literal typing is context-independent — the
+weakening that lifts `+StoreWellTyped+`’s
+`+HasType emptyTypeEnv (.lit v) t+` into the arbitrary `+Γ+`
+statement-level typing uses). Hole-free (`+hasType_lit_any+` needs *no*
+axioms). _Correction to the prior note:_ the expression `+Step+` is
+*not* closed-term-only — it has an `+sVar+` rule that resolves variables
+from `+ρ+`; the closed-context use was only in the
+`+emptyTypeEnv+`-stated `+progress+`/`+preservation+`. So the remaining
+work is a generalized store-typed preservation (`+HasType Γ e t+` under
+`+StoreWellTyped Γ ρ+`), then the statement-execution relation itself.
+* [~] *Phase 1b (store-typed preservation)* —
+`+store_step_preservation+`: expression preservation generalized from
+the empty context to an arbitrary `+Γ+` under `+StoreWellTyped Γ ρ+`
+(`+HasType Γ e t → Step e ρ e' ρ' → HasType Γ e' t+`). This is the form
+statement execution needs — expressions inside a statement are typed in
+the _running_ context, not the empty one. Mirrors `+preservation+`; the
+*only* case that differs is `+sVar+`, which discharges via
+`+store_wellTyped_lookup+` + `+hasType_lit_any+` (the runtime value
+bound to `+x+` has the type `+Γ+` assigns `+x+`) instead of the
+empty-context contradiction. A `+preservation_via_store+` corollary
+confirms it subsumes the closed theorem (empty context is vacuously
+store-typed). Hole-free (classical kernel base: `+propext+`,
+`+Classical.choice+`, `+Quot.sound+`). Purely additive — the merged
+`+preservation+`/`+type_safety+` are untouched.
+* [~] *Phase 1b (statement execution — simple fragment)* — a big-step
+execution relation `+StmtExec+`/`+StmtsExec+` (mutual) and its
+*store-typing preservation* for the simple statements (no embedded
+blocks): `+complain+`, `+expr+`, `+varDecl+`, `+assign+`, `+return_+`.
+Each evaluates its expression to a value via the closed-store
+`+MultiStep+` then applies its store effect; `+stmt_exec_preservation+`
+/ `+stmts_exec_preservation+` show a well-typed statement/block run in a
+well-typed store yields a store well-typed against the statement’s
+output context (`+StmtWellTyped Γ s Γ'+`). Supporting lemmas:
+`+store_multiStep_preservation+` (multi-step store-typed preservation)
+and `+store_wellTyped_update+` (overwriting an already-declared variable
+at its type — the `+assign+` analogue of `+store_wellTyped_extend+`).
+Two executable smoke tests (`+let x = 0+`; the block `+let x = 0; x+`).
+Hole-free (classical kernel base; `+store_wellTyped_update+` needs
+none). Purely additive. _Deferred to the next increment:_ the
+control-flow forms `+if+`/`+loop+`/`+attempt+`/`+consent+`, which
+introduce *block scoping* in the flat `+Env+` model (a block-local
+`+varDecl+` shadowing an outer variable at a different type would break
+preservation against the outer context unless the store is restored on
+block exit). That store-restoration design is the open modelling
+decision for control-flow execution; `+return_+`’s value-propagation /
+block short-circuit (relevant once function calls are modelled) is
+likewise deferred.
+* [~] *Phase 1b (control-flow execution + block scoping)* — the four
+control-flow forms `+if+`/`+loop+`/`+attempt+`/`+consent+` added to
+`+StmtExec+`, with *faithful lexical scoping* (option A, the Rust
+`+Environment{bindings,parent}+` discipline): on block exit, the names a
+block _declared_ (`+declaredVars+`, via the `+varDecl+`s at its top
+level) are rolled back to their entry values by `+restoreVars+`, while
+assignments to _enclosing_ variables persist. `+loopStep+` recurses on
+the restored store, so outer-variable mutations carry across iterations
+while declarations re-scope each pass; `+attemptOk+` selectively
+restores, `+attemptErr+` restores the entry store (op-sem
+`+[B-Attempt-Err]+`); `+consentGrant/Deny+`. The
+`+stmt_exec_preservation+`/`+stmts_exec_preservation+` store-typing
+theorems are upgraded to the *full mutual induction* (via the
+`+StmtExec.rec+` mutual recursor — `+induction+` does not support mutual
+inductives, and the loop’s same-statement recursion is
+non-AST-structural), bridged by `+ctx_agrees_off_declared+` (a statics
+lemma: `+Γ₁+` agrees with `+Γ+` off the declared names) +
+`+store_wellTyped_restore+`. Two faithfulness smoke tests run real
+programs: a block-local declaration is rolled back (does not escape),
+and an outer-variable mutation persists through a block. Hole-free
+(classical kernel base; the scoping lemmas need only `+propext+`).
+_Documented divergences:_ `+loop+` is bool/while-guarded (inheriting the
+merged `+StmtWellTyped.loop : … .bool+`) whereas the interpreters use a
+counted-`+int+` loop (deferred — changing it edits merged statics);
+`+consent+`/`+attempt+` abstract the permission oracle and result
+channel; early exit (return/break/continue) is unmodeled. This is a
+preservation-only result (no statement-progress/determinism claim).
+_Adversarially reviewed_ (faithfulness vs the Rust interpreter,
+non-vacuity, scoping edge-cases, honesty): *0 soundness defects* — the
+scary cases (loop non-termination has no derivation; `+ifTrue+` over an
+arbitrary `+ρb+`; duplicate declarations) were all confirmed sound; the
+confirmed findings were documentation/honesty improvements (surfacing
+the divergences above, clarifying `+attemptErr+` as a store-effect
+abstraction), folded into the file header and §7e comments.
+* [ ] Phase 1 (cont.: `+[T-Call]+` after 1b), 1b (counted-int loop;
+statement progress/determinism), 1c — type-safety + operational
+metatheory.
+* [ ] Phase 2b, 2c — consent + capability state machines.
+* [ ] Phase 3a (+3b) — HM inference.
+* [ ] Phase 4a–4c — compiler / parser / WASM.
+* [ ] Phase 5a, 6, 7 — concrete category theory, structural complexity,
+scoped concurrency.
+* [ ] Axis 2 — (E) normative model, (A) differential testing.
diff --git a/docs/proofs/VERIFICATION-ROADMAP.md b/docs/proofs/VERIFICATION-ROADMAP.md
deleted file mode 100644
index c7c37b6..0000000
--- a/docs/proofs/VERIFICATION-ROADMAP.md
+++ /dev/null
@@ -1,213 +0,0 @@
-
-
-
-# WokeLang Formal-Verification Roadmap
-
-Scope for taking WokeLang from "a model of the expression core + grammar
-metatheory is machine-checked" to "fully proved." Companion to
-[`verification/AUDIT.md`](verification/AUDIT.md),
-[`verification/GRAMMAR-PROOF-INVENTORY.md`](verification/GRAMMAR-PROOF-INVENTORY.md),
-and [`../../PROOF-NEEDS.md`](../../PROOF-NEEDS.md). Derived from a four-part survey
-of every proof document and the implementation (2026-06).
-
-## The two axes (and the honest reality)
-
-"Fully proved across its entire extent" means two very different things:
-
-- **Axis 1 — breadth of the *models*:** mechanize every prose proof (type
- inference, semantics, compiler, security, complexity, concurrency) in Lean 4
- (4.30.0, Mathlib-free, single-file) and/or Coq 8.18.0. Mostly tractable; a few
- items are infeasible without Mathlib.
-- **Axis 2 — depth, *model ↔ real code*:** connect the proofs to the actual
- **~23k-LOC Rust** implementation (plus a divergent ~1.1k-LOC OCaml `core/`).
- There is currently **no extraction, no refinement proof, no translation
- validation** in place. The machine-checked proofs cover roughly **10–15 %** of
- the 94-production surface language, and they verify **models, not code**.
-
-> **Reality check.** Literal "fully proved against the shipping Rust" is
-> CompCert + RustBelt scale — multiple person-years, research-grade tooling that
-> does not exist for this codebase (async / `tokio` / proc-macros). It is a new
-> research program, not an extension of the present work. What *is* achievable is
-> **"the language model fully proved, plus an empirical bridge to the code."**
-
-## Current baseline (machine-checked, hole-free, CI-gated)
-
-| File | Covers |
-|---|---|
-| `verification/WokeLang.lean` / `.v` | expression-core **type safety** (progress, preservation, type-safety, canonical forms, arrays, `Result`/`unwrap` panic); statement **typing + execution** (all nine forms — simple + control-flow with faithful lexical block scoping; store-typing preservation); consent monotonicity/preservation; capability preorder |
-| `verification/WokeGrammar.lean` | verified-parser core (soundness, completeness, termination, precedence, determinism) |
-| `verification/WokeGrammarStructure.{lean,v}` | no-left-recursion (whole grammar), maximal munch, keyword priority, LL(1)✗/LL(2)✓ |
-| `verification/WokeGrammar{CFL,Regular,Pumping}.lean` | CFL closure, non-regularity, the CFL pumping lemma, `aⁿbⁿcⁿ ∉ CFL`, ∩ non-closure |
-
-## Fix-first: five spec bugs (each Small, do as the phase is reached)
-
-These are *wrong as written* and will block the corresponding proofs:
-
-1. **HM `unify(Int,Float)=promote`** makes the "most general unifier" theorems
- false — model widening as **subtyping**, not unification. (blocks Phase 3a)
-2. **`Step` is non-deterministic** (`sArrayVal` overlaps element rules) — blocks
- any determinism proof. (blocks Phase 1c)
-3. **Float `==` reflexivity** is false on `NaN` — the memory-model equality claim
- needs restating (decidable structural eq, or exclude floats).
-4. **Unbounded `Int` vs `ℤ₆₄`** — the model uses ℤ; the language is 64-bit
- wrapping. Affects arithmetic laws and compiler/WASM correctness. (cross-cutting)
-5. **Three-way divergence** — Rust, OCaml `core/`, and the Lean/Coq models
- disagree on `Result`/units/coercions, so "the impl refines the proof" is
- currently ill-posed. Resolve by making one model **normative**. (blocks Axis 2)
-
-## Axis 1 — phases (dependency-ordered)
-
-| Phase | Deliverable | Effort | Mathlib-free? | Depends on |
-|---|---|---|---|---|
-| **1. Full type safety** | substitution lemma + `[T-Call]`/`Φ` + indexing → progress/preservation for the full *expression* language | M | yes | core |
-| **1b. Statement dynamics** | statement execution relation + store-typing preservation | L | yes | 1 |
-| **1c. Operational metatheory** | fix determinism, add big-step, big↔small equivalence | M | yes | bug 2, 1b |
-| **2a. Capability order** | antisymmetry + `hasCapability` satisfaction lemmas (+ Coq `cap_subsumes_trans`) | S | yes | — |
-| **2b. Consent state machine** | duration/expiry, protocol completeness + determinism + unforgability, isolation | M | yes (excl. IO persistence, LTL/CTL) | — |
-| **2c. Capability state machine** | no-privilege-escalation, confinement, revocation, temporal, audit | M | yes | 2a |
-| **3a. HM inference (soundness)** | `unify` (well-founded + occurs check) + Algorithm W **soundness** | L | yes (hand-rolled `FTV`/`Subst`) | 1, bug 1 |
-| **3b. HM completeness** | principal types / most-general | XL | yes but large | 3a |
-| **4a. Compiler simulation** | Lean bytecode IR + VM + `compile` + forward simulation (interpret↔VM) | L | yes | 1c |
-| **4b. Lexer/parser in Lean** | `tokenize`/`parse` + EBNF conformance (beyond current structural facts) | M ea. | yes | — |
-| **4c. WASM preservation** | WASM-subset semantics + preservation | L | yes (partial) | 4a |
-| **5a. Category theory (concrete)** | functor / monad / naturality laws for `Maybe`/`Result`/`List`/`State` | S–M | yes | — |
-| **6. Complexity (structural)** | AST-size + `bytecode ≤ k·AST` size theorems only | L | yes | 4a |
-| **7. Concurrency (scoped)** | interleaving semantics + worker isolation + message-non-loss safety | L | yes | 1b |
-
-## Axis 1 — explicitly out of scope / research-grade
-
-- **Denotational adequacy** (`𝕍 ≅ … + (𝕍→𝕍⊥)`, fixpoints): recursive
- function-summand fails Lean's positivity check; needs Scott domain theory →
- XL, likely infeasible single-file/Mathlib-free. Restrict to the first-order
- fragment (M) or descope.
-- **Category-theory headline claims** (CCC, all finite limits/colimits,
- adjunctions, Yoneda, topos): need Mathlib's `CategoryTheory` (policy conflict);
- several are not well-posed about an actual defined category. Descope or
- grant a one-module Mathlib exception.
-- **Complexity asymptotics** (`O(·)`, inverse-Ackermann/union-find, crate
- constants): claims about Rust + external crates, not witnessable in a model.
-- **Concurrency race/deadlock freedom + CSP trace-equivalence**: evidence is Rust
- ownership / a not-yet-built async runtime — not faithfully mechanizable.
-- **Memory model** (use-after-free, double-free, data races, UTF-8,
- atomic-write persistence): Rust/POSIX host properties, *not* object-language
- theorems. Only bounds-safety + equality-relation are real (S).
-
-## Axis 2 — model ↔ implementation
-
-| Approach | Guarantee | Effort | Reality |
-|---|---|---|---|
-| **(E) Make one model normative; kill 3-way divergence** | well-posedness | M | **Prerequisite** for any bridge being meaningful |
-| **(A) Differential + property-based testing** | empirical | S–M | **Only realistic near-term bridge**; tooling exists (`proptest`, `fuzz/`, `conformance/`) |
-| **(B) Translation validation for the parser** | per-run certificate | L | model already half-supports it (renderer inversion) |
-| **(C) Coq→OCaml extraction of a *new* reference interpreter** | extracted = verified | L | idiomatic, but *replaces* `core/eval.ml` rather than validating it |
-| **(D) Rust refinement (Aeneas/Creusot/Verus), core fragment only** | impl ⊑ model | XL | research-grade; async/macros out of tool scope |
-| **Full verified source→WASM compiler** | end-to-end | XL (multi-person-year) | CompCert-scale; new project |
-
-## Recommended target — three tiers
-
-- **Tier 1 — the model is fully proved.** Phases 1, 1b, 1c, 2a–2c, 3a, 4a plus the
- five spec-bug fixes: full type safety, sound type inference, a verified compiler
- simulation, and real security state machines. The achievable bulk — all
- Mathlib-free, extending the hole-free core.
-- **Tier 2 — empirical bridge to the code.** (E) + (A): resolve divergence and
- stand up cross-backend differential / property testing. Real confidence the
- Rust/OCaml code matches the verified model.
-- **Tier 3 — true refinement / verified compilation.** (D) and source→WASM:
- explicitly a research program (multi-person-year). Not a committed deliverable.
-
-**First increment** (lowest risk, highest leverage): the five spec-bug fixes +
-**Phase 2a** (capability order, S) + **Phase 1** (full-expression type safety via
-the substitution lemma, M). These extend the existing hole-free file directly and
-unlock Phases 1c / 3a / 4a.
-
-## Progress
-
-- [x] **Phase 2a (Lean)** — capability partial order (`capSubsumes_antisymm`,
- completing `_refl`/`_trans`) + satisfaction lemmas (`hasCapability_mono`,
- `hasCapability_subsumes`). Coq parity (`cap_subsumes_trans`/`_antisymm`) remains
- a deliberate follow-up — the author left it unproven rather than ship fragile
- 6×6×6 automation; a clean Coq proof wants a `cap_subsumes` characterization lemma.
-- [~] **Phase 1 (partial)** — the **Substitution Lemma** (`subst` + `subst_preserves_typing`,
- type-safety.md Lemma 3.4) is mechanized on the hole-free core, by induction on the
- typing derivation with the context generalized (axioms `propext`, `Quot.sound`). This is
- the prerequisite for `[T-Call]`'s preservation case and for Algorithm W soundness (3a).
- *Finding:* `[T-Call]` dynamics here are NOT the assumed simple body-substitution —
- `Expr.call` is by name and `TopItem.functionDef` bodies are **statement lists**, so call
- reduction entangles with statement *execution* and belongs with **Phase 1b** (statement
- dynamics), not this step. There is also no `index` constructor, so `[T-Index]` requires an
- AST extension. Roadmap refined accordingly.
-- [~] **Phase 1b (foundation)** — **store typing** (`StoreWellTyped`) bridging the
- static `TypeEnv` and the runtime `Env`, with the three lemmas the statement-execution
- preservation proofs rest on: `store_wellTyped_empty` (empty store types against the
- empty context), `store_wellTyped_lookup` (a typed variable resolves to a value of its
- type), and `store_wellTyped_extend` (extending context+store in lockstep — exactly a
- `varDecl` — preserves store typing). Hole-free (axiom `propext` only).
-- [~] **Phase 1b (substrate)** — **expression-evaluation invariants under a store**, the
- layer the statement-execution relation sits on: `step_store_invariant` and
- `multiStep_store_invariant` (expression evaluation never mutates `ρ` — so a sub-evaluation
- inside a statement can't disturb the bindings the statement effect then acts on), and
- `hasType_lit_any` (literal typing is context-independent — the weakening that lifts
- `StoreWellTyped`'s `HasType emptyTypeEnv (.lit v) t` into the arbitrary `Γ` statement-level
- typing uses). Hole-free (`hasType_lit_any` needs **no** axioms). *Correction to the prior
- note:* the expression `Step` is **not** closed-term-only — it has an `sVar` rule that
- resolves variables from `ρ`; the closed-context use was only in the `emptyTypeEnv`-stated
- `progress`/`preservation`. So the remaining work is a generalized store-typed preservation
- (`HasType Γ e t` under `StoreWellTyped Γ ρ`), then the statement-execution relation itself.
-- [~] **Phase 1b (store-typed preservation)** — `store_step_preservation`: expression
- preservation generalized from the empty context to an arbitrary `Γ` under `StoreWellTyped Γ ρ`
- (`HasType Γ e t → Step e ρ e' ρ' → HasType Γ e' t`). This is the form statement execution
- needs — expressions inside a statement are typed in the *running* context, not the empty one.
- Mirrors `preservation`; the **only** case that differs is `sVar`, which discharges via
- `store_wellTyped_lookup` + `hasType_lit_any` (the runtime value bound to `x` has the type
- `Γ` assigns `x`) instead of the empty-context contradiction. A `preservation_via_store`
- corollary confirms it subsumes the closed theorem (empty context is vacuously store-typed).
- Hole-free (classical kernel base: `propext`, `Classical.choice`, `Quot.sound`). Purely
- additive — the merged `preservation`/`type_safety` are untouched.
-- [~] **Phase 1b (statement execution — simple fragment)** — a big-step execution relation
- `StmtExec`/`StmtsExec` (mutual) and its **store-typing preservation** for the simple
- statements (no embedded blocks): `complain`, `expr`, `varDecl`, `assign`, `return_`. Each
- evaluates its expression to a value via the closed-store `MultiStep` then applies its store
- effect; `stmt_exec_preservation` / `stmts_exec_preservation` show a well-typed statement/block
- run in a well-typed store yields a store well-typed against the statement's output context
- (`StmtWellTyped Γ s Γ'`). Supporting lemmas: `store_multiStep_preservation` (multi-step
- store-typed preservation) and `store_wellTyped_update` (overwriting an already-declared
- variable at its type — the `assign` analogue of `store_wellTyped_extend`). Two executable
- smoke tests (`let x = 0`; the block `let x = 0; x`). Hole-free (classical kernel base;
- `store_wellTyped_update` needs none). Purely additive.
- *Deferred to the next increment:* the control-flow forms `if`/`loop`/`attempt`/`consent`,
- which introduce **block scoping** in the flat `Env` model (a block-local `varDecl` shadowing
- an outer variable at a different type would break preservation against the outer context
- unless the store is restored on block exit). That store-restoration design is the open
- modelling decision for control-flow execution; `return_`'s value-propagation / block
- short-circuit (relevant once function calls are modelled) is likewise deferred.
-- [~] **Phase 1b (control-flow execution + block scoping)** — the four control-flow forms
- `if`/`loop`/`attempt`/`consent` added to `StmtExec`, with **faithful lexical scoping**
- (option A, the Rust `Environment{bindings,parent}` discipline): on block exit, the names a
- block *declared* (`declaredVars`, via the `varDecl`s at its top level) are rolled back to
- their entry values by `restoreVars`, while assignments to *enclosing* variables persist.
- `loopStep` recurses on the restored store, so outer-variable mutations carry across
- iterations while declarations re-scope each pass; `attemptOk` selectively restores,
- `attemptErr` restores the entry store (op-sem `[B-Attempt-Err]`); `consentGrant/Deny`.
- The `stmt_exec_preservation`/`stmts_exec_preservation` store-typing theorems are upgraded to
- the **full mutual induction** (via the `StmtExec.rec` mutual recursor — `induction` does not
- support mutual inductives, and the loop's same-statement recursion is non-AST-structural),
- bridged by `ctx_agrees_off_declared` (a statics lemma: `Γ₁` agrees with `Γ` off the declared
- names) + `store_wellTyped_restore`. Two faithfulness smoke tests run real programs: a
- block-local declaration is rolled back (does not escape), and an outer-variable mutation
- persists through a block. Hole-free (classical kernel base; the scoping lemmas need only
- `propext`). *Documented divergences:* `loop` is bool/while-guarded (inheriting the merged
- `StmtWellTyped.loop : … .bool`) whereas the interpreters use a counted-`int` loop (deferred —
- changing it edits merged statics); `consent`/`attempt` abstract the permission oracle and
- result channel; early exit (return/break/continue) is unmodeled. This is a preservation-only
- result (no statement-progress/determinism claim). *Adversarially reviewed* (faithfulness vs the
- Rust interpreter, non-vacuity, scoping edge-cases, honesty): **0 soundness defects** — the
- scary cases (loop non-termination has no derivation; `ifTrue` over an arbitrary `ρb`; duplicate
- declarations) were all confirmed sound; the confirmed findings were documentation/honesty
- improvements (surfacing the divergences above, clarifying `attemptErr` as a store-effect
- abstraction), folded into the file header and §7e comments.
-- [ ] Phase 1 (cont.: `[T-Call]` after 1b), 1b (counted-int loop; statement progress/determinism), 1c — type-safety + operational metatheory.
-- [ ] Phase 2b, 2c — consent + capability state machines.
-- [ ] Phase 3a (+3b) — HM inference.
-- [ ] Phase 4a–4c — compiler / parser / WASM.
-- [ ] Phase 5a, 6, 7 — concrete category theory, structural complexity, scoped concurrency.
-- [ ] Axis 2 — (E) normative model, (A) differential testing.
diff --git a/docs/proofs/compiler/memory-model.adoc b/docs/proofs/compiler/memory-model.adoc
new file mode 100644
index 0000000..b6d8ac3
--- /dev/null
+++ b/docs/proofs/compiler/memory-model.adoc
@@ -0,0 +1,445 @@
+== WokeLang Memory Model and Safety
+
+This document specifies the memory model and proves memory safety
+properties for WokeLang.
+
+=== 1. Memory Model Overview
+
+==== 1.1 Value Representation
+
+WokeLang values are represented as Rust enums:
+
+[source,rust]
+----
+pub enum Value {
+ Int(i64), // 8 bytes
+ Float(f64), // 8 bytes
+ String(String), // 24 bytes (ptr, len, cap)
+ Bool(bool), // 1 byte + padding
+ Unit, // 0 bytes (tag only)
+ Array(Vec), // 24 bytes (ptr, len, cap)
+ Okay(Box), // 8 bytes (ptr)
+ Oops(String), // 24 bytes
+ Record(HashMap), // ~48 bytes
+}
+----
+
+==== 1.2 Memory Layout
+
+....
+┌──────────────────────────────────────────────────────────┐
+│ Stack │
+├──────────────────────────────────────────────────────────┤
+│ Local variables (Value enums) │
+│ Function arguments │
+│ Return addresses │
+├──────────────────────────────────────────────────────────┤
+│ Heap │
+├──────────────────────────────────────────────────────────┤
+│ String contents (allocated by std::string::String) │
+│ Array elements (allocated by Vec) │
+│ Boxed values (Result inner values) │
+│ HashMap buckets (Record fields) │
+└──────────────────────────────────────────────────────────┘
+....
+
+'''''
+
+=== 2. Ownership Model
+
+==== 2.1 Rust Ownership Semantics
+
+WokeLang inherits Rust’s ownership model:
+
+[arabic]
+. *Each value has a single owner*
+. *When the owner goes out of scope, the value is dropped*
+. *Values can be borrowed (immutably or mutably)*
+. *Mutable borrows are exclusive*
+
+==== 2.2 Value Cloning
+
+WokeLang values implement `+Clone+`:
+
+[source,rust]
+----
+impl Clone for Value {
+ fn clone(&self) -> Self {
+ match self {
+ Value::Int(n) => Value::Int(*n),
+ Value::String(s) => Value::String(s.clone()), // Deep copy
+ Value::Array(a) => Value::Array(a.clone()), // Deep copy
+ // ...
+ }
+ }
+}
+----
+
+*Theorem 2.1:* Value cloning produces independent copies.
+
+*Proof:* Each `+clone()+` call allocates new heap memory for
+heap-allocated types (String, Vec). No pointers are shared between
+original and clone. □
+
+==== 2.3 Environment Semantics
+
+Variable binding clones values:
+
+[source,rust]
+----
+fn define(&mut self, name: String, value: Value) {
+ if let Some(scope) = self.scopes.last_mut() {
+ scope.insert(name, value); // value is moved into HashMap
+ }
+}
+----
+
+Variable lookup clones values:
+
+[source,rust]
+----
+fn get(&self, name: &str) -> Option {
+ for scope in self.scopes.iter().rev() {
+ if let Some(value) = scope.get(name) {
+ return Some(value.clone()); // Clone on read
+ }
+ }
+ None
+}
+----
+
+'''''
+
+=== 3. Memory Safety Proofs
+
+==== 3.1 No Use-After-Free
+
+*Theorem 3.1 (No Use-After-Free):* WokeLang programs cannot access freed
+memory.
+
+*Proof:* 1. All heap allocations are managed by Rust’s ownership system
+2. Values are dropped when their owning scope ends 3. References to
+values are cloned, not borrowed across scope boundaries 4. Rust’s borrow
+checker prevents use-after-free at compile time 5. No unsafe code in the
+interpreter
+
+Therefore, use-after-free is impossible. □
+
+==== 3.2 No Double-Free
+
+*Theorem 3.2 (No Double-Free):* Memory is freed exactly once.
+
+*Proof:* 1. Each value has a single owner 2. Drop is called exactly once
+when owner goes out of scope 3. Clone creates new owners, not aliases 4.
+Rust guarantees single drop
+
+Therefore, double-free is impossible. □
+
+==== 3.3 No Null Pointer Dereference
+
+*Theorem 3.3 (No Null Dereference):* WokeLang cannot dereference null
+pointers.
+
+*Proof:* 1. Rust has no null pointers (Option instead) 2. WokeLang’s
+Value enum has no None variant for non-optional types 3. Box always
+contains a valid pointer 4. Vec and String contain valid (possibly
+zero-length) allocations
+
+Therefore, null dereference is impossible. □
+
+==== 3.4 No Buffer Overflow
+
+*Theorem 3.4 (No Buffer Overflow):* Array accesses are bounds-checked.
+
+*Proof:* 1. Array indexing uses `+Vec::get()+` which returns
+`+Option<&T>+` 2. Out-of-bounds access returns `+None+` or panics (in
+some paths) 3. Runtime error is raised, not undefined behavior
+
+[source,rust]
+----
+match &args[0] {
+ Value::Array(a) => Ok(Some(Value::Int(a.len() as i64))),
+ _ => Err(RuntimeError::TypeError(...)),
+}
+----
+
+Therefore, buffer overflow is impossible. □
+
+==== 3.5 No Data Races
+
+*Theorem 3.5 (No Data Races):* Concurrent access is safe.
+
+*Proof:* 1. The interpreter is single-threaded (synchronous worker
+execution) 2. Each worker has its own environment 3. Message passing
+clones values 4. No mutable shared state between workers
+
+For true concurrent workers (future work): - MPSC channels are
+thread-safe - Arc/Mutex would protect shared state - Rust prevents data
+races at compile time
+
+□
+
+'''''
+
+=== 4. Allocation Patterns
+
+==== 4.1 Stack Allocation
+
+Small values are stack-allocated: - Int, Float, Bool, Unit: Always on
+stack - Enum discriminant: Always on stack
+
+==== 4.2 Heap Allocation
+
+Complex values require heap allocation: - String: Character data on heap
+- Array: Element vector on heap - Record: HashMap buckets on heap -
+Okay/Oops: Boxed inner value on heap
+
+==== 4.3 Allocation Complexity
+
+[cols=",,",options="header",]
+|===
+|Operation |Allocations |Complexity
+|Integer literal |0 |O(1)
+|String literal |1 |O(n)
+|Array literal |1 + Σelemₛ |O(n)
+|Variable read |Clone costs |O(size)
+|Function call |Frame + locals |O(params + locals)
+|===
+
+'''''
+
+=== 5. Garbage Collection
+
+==== 5.1 Current Model: Reference Counting (Implicit)
+
+WokeLang uses Rust’s ownership, which effectively implements
+deterministic destruction:
+
+....
+Value created → Value cloned → ... → Last owner dropped → Memory freed
+....
+
+This is *not* garbage collection but *RAII* (Resource Acquisition Is
+Initialization).
+
+==== 5.2 Properties
+
+[cols=",",options="header",]
+|===
+|Property |Value
+|Deterministic destruction |Yes
+|Pause-free |Yes
+|Cycle handling |N/A (no cycles in Value)
+|Memory overhead |None
+|Fragmentation |Allocator-dependent
+|===
+
+==== 5.3 Cycle Prevention
+
+*Theorem 5.1:* WokeLang Value types cannot form cycles.
+
+*Proof:* - Value::Array contains Vec (values, not references) -
+Value::Okay contains Box (owned, not reference) - No Rc/Arc types used -
+No self-referential structures possible
+
+Therefore, no cycles can form, and reference counting (implicit via
+Drop) correctly frees all memory. □
+
+'''''
+
+=== 6. Memory Bounds
+
+==== 6.1 Stack Limits
+
+[cols=",,",options="header",]
+|===
+|Limit |Value |Justification
+|Max call depth |1000 |Prevents stack overflow
+|Max stack size |10000 values |VM configuration
+|Frame size |~100 bytes |Typical function frame
+|===
+
+[source,rust]
+----
+const MAX_CALL_DEPTH: usize = 1000;
+const MAX_STACK_SIZE: usize = 10000;
+----
+
+==== 6.2 Heap Limits
+
+[cols=",,",options="header",]
+|===
+|Limit |Value |Justification
+|Max string length |2^63 - 1 |Rust String limit
+|Max array length |2^63 - 1 |Rust Vec limit
+|Max total heap |OS-dependent |System allocator limit
+|===
+
+==== 6.3 Recursion Safety
+
+*Theorem 6.1:* Stack overflow is prevented.
+
+*Proof:*
+
+[source,rust]
+----
+if self.call_stack.len() >= self.max_call_depth {
+ return Err(VMError { message: "Maximum call depth exceeded" });
+}
+----
+
+The check before each call prevents unbounded recursion from overflowing
+the Rust stack. □
+
+'''''
+
+=== 7. Value Equality
+
+==== 7.1 Structural Equality
+
+Values implement `+PartialEq+`:
+
+[source,rust]
+----
+impl PartialEq for Value {
+ fn eq(&self, other: &Self) -> bool {
+ match (self, other) {
+ (Value::Int(a), Value::Int(b)) => a == b,
+ (Value::Float(a), Value::Float(b)) => a == b,
+ (Value::String(a), Value::String(b)) => a == b,
+ (Value::Array(a), Value::Array(b)) => a == b, // Deep comparison
+ // ...
+ _ => false,
+ }
+ }
+}
+----
+
+==== 7.2 Equality Properties
+
+*Theorem 7.1:* Value equality is an equivalence relation.
+
+*Proof:* - Reflexive: v == v (by structural equality of components) -
+Symmetric: v == w ⟹ w == v (symmetric match arms) - Transitive: v == w ∧
+w == x ⟹ v == x (component equality is transitive) □
+
+'''''
+
+=== 8. String Representation
+
+==== 8.1 UTF-8 Encoding
+
+WokeLang strings use Rust’s String type: - Valid UTF-8 guaranteed - O(1)
+length (in bytes) - O(n) character iteration
+
+==== 8.2 String Operations
+
+[cols=",,",options="header",]
+|===
+|Operation |Allocation |Complexity
+|Literal |1 |O(n)
+|Concatenation |1 |O(n + m)
+|Comparison |0 |O(min(n, m))
+|Substring |1 |O(k)
+|===
+
+==== 8.3 String Safety
+
+*Theorem 8.1:* All WokeLang strings are valid UTF-8.
+
+*Proof:* 1. String literals are validated at parse time 2. Concatenation
+preserves UTF-8 (String::push_str checks) 3. No raw byte manipulation
+exposed to user 4. Rust guarantees String invariant
+
+□
+
+'''''
+
+=== 9. Array Semantics
+
+==== 9.1 Homogeneous Arrays
+
+WokeLang arrays are homogeneous at runtime (type-checked statically when
+possible):
+
+[source,rust]
+----
+Value::Array(Vec)
+----
+
+All elements must have compatible types.
+
+==== 9.2 Array Operations
+
+[cols=",,",options="header",]
+|===
+|Operation |Mutates |Allocation
+|Index |No |Clone
+|Push |Yes |Amortized O(1)
+|Pop |Yes |No
+|Concat |No |O(n + m)
+|Map |No |O(n)
+|===
+
+==== 9.3 Array Bounds
+
+[source,rust]
+----
+fn index(&self, arr: &[Value], idx: i64) -> Result {
+ if idx < 0 || idx >= arr.len() as i64 {
+ return Err(RuntimeError::IndexOutOfBounds(idx as usize));
+ }
+ Ok(arr[idx as usize].clone())
+}
+----
+
+'''''
+
+=== 10. Future Work
+
+==== 10.1 TODO: Copy-on-Write
+
+Optimize cloning with COW:
+
+[source,rust]
+----
+enum Value {
+ // ...
+ String(Arc),
+ Array(Arc<[Value]>),
+}
+----
+
+==== 10.2 TODO: Arena Allocation
+
+Reduce allocation overhead:
+
+[source,rust]
+----
+struct Arena {
+ chunks: Vec>,
+ current: usize,
+}
+----
+
+==== 10.3 TODO: NaN-Boxing
+
+Compact value representation:
+
+[source,rust]
+----
+// All values in 8 bytes using NaN-boxing
+type NaNBoxedValue = u64;
+----
+
+'''''
+
+=== References
+
+[arabic]
+. Klabnik, S. and Nichols, C. (2019). "`The Rust Programming Language`"
+. Jung, R. et al. (2017). "`RustBelt: Securing the Foundations of the
+Rust Programming Language`"
+. Matsakis, N. and Klock, F. (2014). "`The Rust Language`"
+. Stroustrup, B. (1994). "`The Design and Evolution of C++`" (RAII
+origin)
diff --git a/docs/proofs/compiler/memory-model.md b/docs/proofs/compiler/memory-model.md
deleted file mode 100644
index bca1d76..0000000
--- a/docs/proofs/compiler/memory-model.md
+++ /dev/null
@@ -1,425 +0,0 @@
-
-# WokeLang Memory Model and Safety
-
-This document specifies the memory model and proves memory safety properties for WokeLang.
-
-## 1. Memory Model Overview
-
-### 1.1 Value Representation
-
-WokeLang values are represented as Rust enums:
-
-```rust
-pub enum Value {
- Int(i64), // 8 bytes
- Float(f64), // 8 bytes
- String(String), // 24 bytes (ptr, len, cap)
- Bool(bool), // 1 byte + padding
- Unit, // 0 bytes (tag only)
- Array(Vec), // 24 bytes (ptr, len, cap)
- Okay(Box), // 8 bytes (ptr)
- Oops(String), // 24 bytes
- Record(HashMap), // ~48 bytes
-}
-```
-
-### 1.2 Memory Layout
-
-```
-┌──────────────────────────────────────────────────────────┐
-│ Stack │
-├──────────────────────────────────────────────────────────┤
-│ Local variables (Value enums) │
-│ Function arguments │
-│ Return addresses │
-├──────────────────────────────────────────────────────────┤
-│ Heap │
-├──────────────────────────────────────────────────────────┤
-│ String contents (allocated by std::string::String) │
-│ Array elements (allocated by Vec) │
-│ Boxed values (Result inner values) │
-│ HashMap buckets (Record fields) │
-└──────────────────────────────────────────────────────────┘
-```
-
----
-
-## 2. Ownership Model
-
-### 2.1 Rust Ownership Semantics
-
-WokeLang inherits Rust's ownership model:
-
-1. **Each value has a single owner**
-2. **When the owner goes out of scope, the value is dropped**
-3. **Values can be borrowed (immutably or mutably)**
-4. **Mutable borrows are exclusive**
-
-### 2.2 Value Cloning
-
-WokeLang values implement `Clone`:
-
-```rust
-impl Clone for Value {
- fn clone(&self) -> Self {
- match self {
- Value::Int(n) => Value::Int(*n),
- Value::String(s) => Value::String(s.clone()), // Deep copy
- Value::Array(a) => Value::Array(a.clone()), // Deep copy
- // ...
- }
- }
-}
-```
-
-**Theorem 2.1:** Value cloning produces independent copies.
-
-**Proof:** Each `clone()` call allocates new heap memory for heap-allocated types (String, Vec). No pointers are shared between original and clone. □
-
-### 2.3 Environment Semantics
-
-Variable binding clones values:
-
-```rust
-fn define(&mut self, name: String, value: Value) {
- if let Some(scope) = self.scopes.last_mut() {
- scope.insert(name, value); // value is moved into HashMap
- }
-}
-```
-
-Variable lookup clones values:
-
-```rust
-fn get(&self, name: &str) -> Option {
- for scope in self.scopes.iter().rev() {
- if let Some(value) = scope.get(name) {
- return Some(value.clone()); // Clone on read
- }
- }
- None
-}
-```
-
----
-
-## 3. Memory Safety Proofs
-
-### 3.1 No Use-After-Free
-
-**Theorem 3.1 (No Use-After-Free):** WokeLang programs cannot access freed memory.
-
-**Proof:**
-1. All heap allocations are managed by Rust's ownership system
-2. Values are dropped when their owning scope ends
-3. References to values are cloned, not borrowed across scope boundaries
-4. Rust's borrow checker prevents use-after-free at compile time
-5. No unsafe code in the interpreter
-
-Therefore, use-after-free is impossible. □
-
-### 3.2 No Double-Free
-
-**Theorem 3.2 (No Double-Free):** Memory is freed exactly once.
-
-**Proof:**
-1. Each value has a single owner
-2. Drop is called exactly once when owner goes out of scope
-3. Clone creates new owners, not aliases
-4. Rust guarantees single drop
-
-Therefore, double-free is impossible. □
-
-### 3.3 No Null Pointer Dereference
-
-**Theorem 3.3 (No Null Dereference):** WokeLang cannot dereference null pointers.
-
-**Proof:**
-1. Rust has no null pointers (Option instead)
-2. WokeLang's Value enum has no None variant for non-optional types
-3. Box always contains a valid pointer
-4. Vec and String contain valid (possibly zero-length) allocations
-
-Therefore, null dereference is impossible. □
-
-### 3.4 No Buffer Overflow
-
-**Theorem 3.4 (No Buffer Overflow):** Array accesses are bounds-checked.
-
-**Proof:**
-1. Array indexing uses `Vec::get()` which returns `Option<&T>`
-2. Out-of-bounds access returns `None` or panics (in some paths)
-3. Runtime error is raised, not undefined behavior
-
-```rust
-match &args[0] {
- Value::Array(a) => Ok(Some(Value::Int(a.len() as i64))),
- _ => Err(RuntimeError::TypeError(...)),
-}
-```
-
-Therefore, buffer overflow is impossible. □
-
-### 3.5 No Data Races
-
-**Theorem 3.5 (No Data Races):** Concurrent access is safe.
-
-**Proof:**
-1. The interpreter is single-threaded (synchronous worker execution)
-2. Each worker has its own environment
-3. Message passing clones values
-4. No mutable shared state between workers
-
-For true concurrent workers (future work):
-- MPSC channels are thread-safe
-- Arc/Mutex would protect shared state
-- Rust prevents data races at compile time
-
-□
-
----
-
-## 4. Allocation Patterns
-
-### 4.1 Stack Allocation
-
-Small values are stack-allocated:
-- Int, Float, Bool, Unit: Always on stack
-- Enum discriminant: Always on stack
-
-### 4.2 Heap Allocation
-
-Complex values require heap allocation:
-- String: Character data on heap
-- Array: Element vector on heap
-- Record: HashMap buckets on heap
-- Okay/Oops: Boxed inner value on heap
-
-### 4.3 Allocation Complexity
-
-| Operation | Allocations | Complexity |
-|-----------|-------------|------------|
-| Integer literal | 0 | O(1) |
-| String literal | 1 | O(n) |
-| Array literal | 1 + Σelemₛ | O(n) |
-| Variable read | Clone costs | O(size) |
-| Function call | Frame + locals | O(params + locals) |
-
----
-
-## 5. Garbage Collection
-
-### 5.1 Current Model: Reference Counting (Implicit)
-
-WokeLang uses Rust's ownership, which effectively implements deterministic destruction:
-
-```
-Value created → Value cloned → ... → Last owner dropped → Memory freed
-```
-
-This is **not** garbage collection but **RAII** (Resource Acquisition Is Initialization).
-
-### 5.2 Properties
-
-| Property | Value |
-|----------|-------|
-| Deterministic destruction | Yes |
-| Pause-free | Yes |
-| Cycle handling | N/A (no cycles in Value) |
-| Memory overhead | None |
-| Fragmentation | Allocator-dependent |
-
-### 5.3 Cycle Prevention
-
-**Theorem 5.1:** WokeLang Value types cannot form cycles.
-
-**Proof:**
-- Value::Array contains Vec (values, not references)
-- Value::Okay contains Box (owned, not reference)
-- No Rc/Arc types used
-- No self-referential structures possible
-
-Therefore, no cycles can form, and reference counting (implicit via Drop) correctly frees all memory. □
-
----
-
-## 6. Memory Bounds
-
-### 6.1 Stack Limits
-
-| Limit | Value | Justification |
-|-------|-------|---------------|
-| Max call depth | 1000 | Prevents stack overflow |
-| Max stack size | 10000 values | VM configuration |
-| Frame size | ~100 bytes | Typical function frame |
-
-```rust
-const MAX_CALL_DEPTH: usize = 1000;
-const MAX_STACK_SIZE: usize = 10000;
-```
-
-### 6.2 Heap Limits
-
-| Limit | Value | Justification |
-|-------|-------|---------------|
-| Max string length | 2^63 - 1 | Rust String limit |
-| Max array length | 2^63 - 1 | Rust Vec limit |
-| Max total heap | OS-dependent | System allocator limit |
-
-### 6.3 Recursion Safety
-
-**Theorem 6.1:** Stack overflow is prevented.
-
-**Proof:**
-```rust
-if self.call_stack.len() >= self.max_call_depth {
- return Err(VMError { message: "Maximum call depth exceeded" });
-}
-```
-
-The check before each call prevents unbounded recursion from overflowing the Rust stack. □
-
----
-
-## 7. Value Equality
-
-### 7.1 Structural Equality
-
-Values implement `PartialEq`:
-
-```rust
-impl PartialEq for Value {
- fn eq(&self, other: &Self) -> bool {
- match (self, other) {
- (Value::Int(a), Value::Int(b)) => a == b,
- (Value::Float(a), Value::Float(b)) => a == b,
- (Value::String(a), Value::String(b)) => a == b,
- (Value::Array(a), Value::Array(b)) => a == b, // Deep comparison
- // ...
- _ => false,
- }
- }
-}
-```
-
-### 7.2 Equality Properties
-
-**Theorem 7.1:** Value equality is an equivalence relation.
-
-**Proof:**
-- Reflexive: v == v (by structural equality of components)
-- Symmetric: v == w ⟹ w == v (symmetric match arms)
-- Transitive: v == w ∧ w == x ⟹ v == x (component equality is transitive)
-□
-
----
-
-## 8. String Representation
-
-### 8.1 UTF-8 Encoding
-
-WokeLang strings use Rust's String type:
-- Valid UTF-8 guaranteed
-- O(1) length (in bytes)
-- O(n) character iteration
-
-### 8.2 String Operations
-
-| Operation | Allocation | Complexity |
-|-----------|------------|------------|
-| Literal | 1 | O(n) |
-| Concatenation | 1 | O(n + m) |
-| Comparison | 0 | O(min(n, m)) |
-| Substring | 1 | O(k) |
-
-### 8.3 String Safety
-
-**Theorem 8.1:** All WokeLang strings are valid UTF-8.
-
-**Proof:**
-1. String literals are validated at parse time
-2. Concatenation preserves UTF-8 (String::push_str checks)
-3. No raw byte manipulation exposed to user
-4. Rust guarantees String invariant
-
-□
-
----
-
-## 9. Array Semantics
-
-### 9.1 Homogeneous Arrays
-
-WokeLang arrays are homogeneous at runtime (type-checked statically when possible):
-
-```rust
-Value::Array(Vec)
-```
-
-All elements must have compatible types.
-
-### 9.2 Array Operations
-
-| Operation | Mutates | Allocation |
-|-----------|---------|------------|
-| Index | No | Clone |
-| Push | Yes | Amortized O(1) |
-| Pop | Yes | No |
-| Concat | No | O(n + m) |
-| Map | No | O(n) |
-
-### 9.3 Array Bounds
-
-```rust
-fn index(&self, arr: &[Value], idx: i64) -> Result {
- if idx < 0 || idx >= arr.len() as i64 {
- return Err(RuntimeError::IndexOutOfBounds(idx as usize));
- }
- Ok(arr[idx as usize].clone())
-}
-```
-
----
-
-## 10. Future Work
-
-### 10.1 TODO: Copy-on-Write
-
-Optimize cloning with COW:
-```rust
-enum Value {
- // ...
- String(Arc),
- Array(Arc<[Value]>),
-}
-```
-
-### 10.2 TODO: Arena Allocation
-
-Reduce allocation overhead:
-```rust
-struct Arena {
- chunks: Vec>,
- current: usize,
-}
-```
-
-### 10.3 TODO: NaN-Boxing
-
-Compact value representation:
-```rust
-// All values in 8 bytes using NaN-boxing
-type NaNBoxedValue = u64;
-```
-
----
-
-## References
-
-1. Klabnik, S. and Nichols, C. (2019). "The Rust Programming Language"
-2. Jung, R. et al. (2017). "RustBelt: Securing the Foundations of the Rust Programming Language"
-3. Matsakis, N. and Klock, F. (2014). "The Rust Language"
-4. Stroustrup, B. (1994). "The Design and Evolution of C++" (RAII origin)
diff --git a/docs/proofs/compiler/semantic-preservation.adoc b/docs/proofs/compiler/semantic-preservation.adoc
new file mode 100644
index 0000000..d9d79cd
--- /dev/null
+++ b/docs/proofs/compiler/semantic-preservation.adoc
@@ -0,0 +1,537 @@
+== WokeLang Compiler Correctness Proofs
+
+This document provides formal proofs of semantic preservation across
+WokeLang’s compilation stages: Source → AST → Bytecode → WASM.
+
+=== 1. Compilation Pipeline
+
+....
+Source Code (.woke)
+ │
+ ▼ Lexer (tokenize)
+ Tokens
+ │
+ ▼ Parser (parse)
+ AST
+ │
+ ├──────────────────────┐
+ │ │
+ ▼ ▼
+ Interpreter Bytecode Compiler
+ (tree-walk) │
+ │ ▼
+ │ Bytecode
+ │ │
+ │ ▼
+ │ VM
+ │ │
+ │ │
+ ▼ ▼
+ Result₁ Result₂
+
+ │
+ └───────► WASM Compiler
+ │
+ ▼
+ WASM Binary
+ │
+ ▼
+ WASM Runtime
+ │
+ ▼
+ Result₃
+....
+
+*Main Theorem (Compiler Correctness):* For all well-typed programs P:
+
+....
+interpret(P) = run_vm(compile_bytecode(P)) = run_wasm(compile_wasm(P))
+....
+
+'''''
+
+=== 2. Lexer Correctness
+
+==== 2.1 Lexer Specification
+
+....
+tokenize : String → Result, LexError>
+....
+
+==== 2.2 Lexer Properties
+
+*Theorem 2.1 (Lexer Totality):* For any input string s, `+tokenize(s)+`
+terminates.
+
+*Proof:* The logos-based lexer processes input character by character
+with finite automata. Each character advances the position. □
+
+*Theorem 2.2 (Lexer Determinism):* For any input s, tokenize(s) produces
+a unique result.
+
+*Proof:* DFA-based tokenization is deterministic by construction. □
+
+*Theorem 2.3 (Token Preservation):*
+`+concat(map(token_text, tokenize(s))) = s+` (modulo whitespace)
+
+*Proof:* Each token records its span in the source. Concatenating spans
+recovers the original input. □
+
+==== 2.3 Token Classification Correctness
+
+*Lemma 2.1 (Keyword Recognition):* All reserved keywords are correctly
+classified.
+
+....
+∀s ∈ Keywords. tokenize(s) = [Token::Keyword(s)]
+....
+
+*Proof:* The Token enum in `+token.rs+` explicitly matches all keywords
+from the grammar. □
+
+'''''
+
+=== 3. Parser Correctness
+
+==== 3.1 Parser Specification
+
+....
+parse : List → Result
+....
+
+==== 3.2 Grammar Conformance
+
+*Theorem 3.1 (Grammar Soundness):* If `+parse(tokens) = Ok(ast)+`, then
+ast conforms to the EBNF grammar.
+
+*Proof:* The recursive descent parser directly encodes the EBNF
+production rules: - `+parse_program()+` implements
+`+program = { top_level_item }+` - `+parse_function()+` implements
+`+function_def = ...+` - `+parse_expression()+` implements the
+expression grammar with correct precedence
+
+Each parse function returns an AST node matching the corresponding
+grammar production. □
+
+*Theorem 3.2 (Grammar Completeness):* If a token sequence is valid
+according to the EBNF grammar, then `+parse(tokens) = Ok(ast)+`.
+
+*Proof:* The parser handles all grammar productions. Error recovery is
+not implemented, so any valid input is accepted. □
+
+==== 3.3 Precedence Correctness
+
+*Theorem 3.3 (Operator Precedence):* The parser produces ASTs respecting
+the defined operator precedence.
+
+Precedence levels (lowest to highest):
+
+....
+1. or
+2. and
+3. == !=
+4. < > <= >=
+5. + -
+6. * / %
+7. - not (unary prefix)
+8. ? () [] (postfix)
+....
+
+*Proof:* The Pratt parser in `+parse_expression_bp()+` uses binding
+powers:
+
+[source,rust]
+----
+fn prefix_binding_power(op: &UnaryOp) -> u8 { 7 }
+fn infix_binding_power(op: &BinaryOp) -> (u8, u8) {
+ match op {
+ Or => (1, 2),
+ And => (3, 4),
+ Eq | NotEq => (5, 6),
+ Lt | Gt | LtEq | GtEq => (7, 8),
+ Add | Sub => (9, 10),
+ Mul | Div | Mod => (11, 12),
+ }
+}
+----
+
+Higher numbers bind tighter. Left-associative operators have left BP <
+right BP. □
+
+==== 3.4 AST Well-Formedness
+
+*Invariant 3.1 (Span Validity):* All AST nodes have valid source spans.
+
+....
+∀node ∈ AST. node.span.start ≤ node.span.end ∧ node.span.end ≤ source.len()
+....
+
+*Invariant 3.2 (Tree Structure):* The AST forms a proper tree (no
+cycles, single root).
+
+'''''
+
+=== 4. Interpreter ↔ Bytecode VM Equivalence
+
+==== 4.1 Compilation Function
+
+....
+compile : AST → CompiledProgram
+....
+
+==== 4.2 Value Correspondence
+
+The interpreter and VM use the same Value type:
+
+[source,rust]
+----
+pub enum Value {
+ Int(i64),
+ Float(f64),
+ String(String),
+ Bool(bool),
+ Unit,
+ Array(Vec),
+ Okay(Box),
+ Oops(String),
+ Record(HashMap),
+}
+----
+
+*Lemma 4.1 (Value Isomorphism):* Interpreter values and VM values are
+identical.
+
+==== 4.3 Environment Correspondence
+
+*Definition:* Environment correspondence
+`+ρ ≈ᵥₘ (stack, locals, globals)+`:
+
+....
+ρ(x) = v ⟺ (x is local i → stack[base + i] = v)
+ ∧ (x is global → globals[x] = v)
+....
+
+==== 4.4 Compilation Correctness Lemmas
+
+*Lemma 4.2 (Expression Compilation):* For expression e with
+`+Γ ⊢ e : τ+`:
+
+....
+If ⟨e, ρ, Φ⟩ ⇓ v and ρ ≈ᵥₘ (stack, locals, globals)
+Then executing compile(e) results in stack' where top(stack') = v
+....
+
+*Proof by structural induction on e:*
+
+*Case e = n (integer literal):* - compile(n) = [Const(idx)] where
+constants[idx] = n - VM: push(constants[idx]) = push(n) ✓
+
+*Case e = x (variable):* - compile(x) = [LoadLocal(i)] if x is local -
+VM: push(stack[base + i]) = push(ρ(x)) ✓
+
+*Case e = e₁ + e₂:* - compile(e₁ + e₂) = compile(e₁); compile(e₂); Add -
+By IH: after compile(e₁), stack has v₁ on top - By IH: after
+compile(e₂), stack has v₂ on top (v₁ below) - After Add: top = v₁ + v₂ ✓
+
+*Case e = f(e₁,…,eₙ):* - compile(f(args)) = compile(e₁); …; compile(eₙ);
+Call(n) - By IH: stack has [v₁, …, vₙ] on top - Call creates new frame,
+executes f’s body - Return pops frame, leaves result on stack ✓
+
+*Lemma 4.3 (Statement Compilation):* For statement s:
+
+....
+If ⟨s, ρ, Φ, C⟩ ⇓ᵇ (result, ρ', C') and ρ ≈ᵥₘ σ
+Then executing compile(s) from σ reaches σ' where ρ' ≈ᵥₘ σ'
+....
+
+*Proof by case analysis on s:*
+
+*Case s = remember x = e:* - compile(s) = compile(e); StoreLocal(i) - e
+evaluates to v (by expression lemma) - StoreLocal stores v at local slot
+i - New environment ρ[x ↦ v] corresponds to updated stack ✓
+
+*Case s = when e \{ s₁ } otherwise \{ s₂ }:*
+
+....
+compile(s) = compile(e)
+ JumpIfFalse(else_label)
+ compile(s₁)
+ Jump(end_label)
+ else_label:
+ compile(s₂)
+ end_label:
+....
+
+* If e evaluates to true: execute s₁ (by IH)
+* If e evaluates to false: jump to else_label, execute s₂ (by IH) ✓
+
+*Case s = repeat e times \{ body }:*
+
+....
+compile(s) = compile(e)
+ StoreLocal(count)
+ loop_start:
+ LoadLocal(count)
+ Const(0)
+ Le
+ JumpIfTrue(loop_end)
+ compile(body)
+ LoadLocal(count)
+ Const(1)
+ Sub
+ StoreLocal(count)
+ Jump(loop_start)
+ loop_end:
+....
+
+* Loop executes body n times, matching interpreter semantics ✓
+
+==== 4.5 Main Theorem (Interpreter-VM Equivalence)
+
+*Theorem 4.1:* For any well-typed program P:
+
+....
+interpret(P) = run_vm(compile(P))
+....
+
+*Proof:* 1. Both start with empty environment/stack 2. Both collect
+function definitions first 3. Both execute main() if present 4. By
+Lemmas 4.2 and 4.3, each step preserves correspondence 5. Final results
+are identical □
+
+'''''
+
+=== 5. Bytecode → WASM Correctness
+
+==== 5.1 WASM Compilation
+
+....
+compile_wasm : AST → Vec (WASM binary)
+....
+
+==== 5.2 WASM Value Mapping
+
+....
+wasm_value(Int(n)) = i64.const n
+wasm_value(Float(f)) = f64.const f -- Note: current impl uses i64 for all
+wasm_value(Bool(true)) = i64.const 1
+wasm_value(Bool(false)) = i64.const 0
+....
+
+==== 5.3 Instruction Correspondence
+
+[cols=",",options="header",]
+|===
+|Bytecode |WASM
+|Const(n) |i64.const n
+|Add |i64.add
+|Sub |i64.sub
+|Mul |i64.mul
+|Div |i64.div_s
+|Mod |i64.rem_s
+|Eq |i64.eq
+|Lt |i64.lt_s
+|Gt |i64.gt_s
+|And |i64.and
+|Or |i64.or
+|Not |i64.eqz
+|LoadLocal(i) |local.get i
+|StoreLocal(i) |local.set i
+|Jump(t) |br t
+|JumpIfFalse(t) |br_if t (with condition negation)
+|Call(n) |call n
+|Return |return
+|===
+
+==== 5.4 Control Flow Translation
+
+*Lemma 5.1 (Conditional Translation):*
+
+....
+compile_wasm(when e { s₁ } otherwise { s₂ }) =
+ compile_wasm(e)
+ if (result i64)
+ compile_wasm(s₁)
+ else
+ compile_wasm(s₂)
+ end
+....
+
+*Lemma 5.2 (Loop Translation):*
+
+....
+compile_wasm(repeat n times { body }) =
+ compile_wasm(n)
+ local.set $count
+ block $exit
+ loop $cont
+ local.get $count
+ i64.const 0
+ i64.le_s
+ br_if $exit
+ compile_wasm(body)
+ local.get $count
+ i64.const 1
+ i64.sub
+ local.set $count
+ br $cont
+ end
+ end
+....
+
+==== 5.5 WASM Correctness Theorem
+
+*Theorem 5.1 (WASM Semantic Preservation):* For pure numeric functions
+f:
+
+....
+interpret(f(args)) = wasm_run(compile_wasm(f), args)
+....
+
+*Proof Sketch:* 1. WASM is a stack machine like the bytecode VM 2. i64
+arithmetic matches Rust’s i64 (two’s complement) 3. Control flow blocks
+map directly 4. Local variables map to WASM locals □
+
+==== 5.6 WASM Limitations
+
+*TODO:* The current WASM compiler has limitations: - Strings not fully
+supported (need memory allocation) - Arrays not supported - Workers not
+supported - Consent blocks skipped
+
+These are marked as `+CompileError::Unsupported+` in the implementation.
+
+'''''
+
+=== 6. Optimization Correctness
+
+==== 6.1 Bytecode Optimizer
+
+The optimizer in `+vm/optimizer.rs+` performs: - Dead code elimination -
+Constant folding - Peephole optimizations
+
+==== 6.2 Optimization Soundness
+
+*Theorem 6.1 (Optimization Soundness):* For any optimization O:
+
+....
+run_vm(optimize(compile(P))) = run_vm(compile(P))
+....
+
+*Proof approach:* Each optimization rule must preserve observable
+behavior:
+
+*Constant Folding:*
+
+....
+Const(a); Const(b); Add → Const(a + b)
+....
+
+Preserved because a + b at compile time = a + b at runtime.
+
+*Dead Code Elimination:*
+
+....
+Const(c); Pop → ε (if c has no side effects)
+....
+
+Preserved because the value is discarded anyway.
+
+*TODO:* Formal proof of each optimization rule.
+
+'''''
+
+=== 7. Type Preservation Across Compilation
+
+==== 7.1 Typed Bytecode
+
+*Definition:* A bytecode instruction sequence is well-typed if: - Stack
+effects are balanced - Types at each point are consistent
+
+==== 7.2 Compilation Preserves Types
+
+*Theorem 7.1:* If `+Γ ⊢ e : τ+` then `+compile(e)+` produces bytecode
+with stack effect `+[] → [τ]+`.
+
+*Proof:* By structural induction, matching each typing rule to its
+compilation: - T-Int: Const(n) has effect [] → [Int] ✓ - T-Add-Int:
+compile(e₁); compile(e₂); Add has effect [] → [Int]; [] → [Int];
+[Int,Int] → [Int] = [] → [Int] ✓ - etc. □
+
+'''''
+
+=== 8. End-to-End Correctness
+
+==== 8.1 Full Pipeline Theorem
+
+*Theorem 8.1 (End-to-End Correctness):* For the full compilation
+pipeline:
+
+....
+∀P. well_typed(P) →
+ ∀input. denotation(P)(input) = execution(compile(P))(input)
+....
+
+Where: - `+denotation(P)+` is the denotational semantics of P -
+`+execution(compile(P))+` is running compiled code
+
+*Proof:* 1. By adequacy theorem (denotational ↔ operational) 2. By
+interpreter correctness (operational ↔ interpreter) 3. By VM equivalence
+(interpreter ↔ VM) 4. By WASM correctness (VM ↔ WASM for supported
+features) □
+
+'''''
+
+=== 9. Verified Compilation Approach
+
+==== 9.1 Future Work: Verified Compiler
+
+To achieve full formal verification, implement:
+
+[arabic]
+. *Compiler in Coq/Lean* with extracted Rust code
+. *CompCert-style* simulation relations
+. *Verified WASM backend* using wasm-verified
+
+==== 9.2 Current Verification Status
+
+[cols=",",options="header",]
+|===
+|Component |Verification Level
+|Lexer |Tested, not proven
+|Parser |Tested, not proven
+|Type Checker |Tested, algorithm correct by construction
+|Interpreter |Reference implementation
+|Bytecode Compiler |Correspondence tested
+|VM |Tested against interpreter
+|WASM Compiler |Partial, limitations documented
+|Optimizer |Each rule should be proven
+|===
+
+'''''
+
+=== 10. Implementation Correspondence
+
+[cols=",",options="header",]
+|===
+|Proof Concept |Implementation File
+|Lexer |`+src/lexer/mod.rs+`, `+token.rs+`
+|Parser |`+src/parser/mod.rs+`
+|AST |`+src/ast/mod.rs+`
+|Interpreter |`+src/interpreter/mod.rs+`
+|Bytecode Compiler |`+src/vm/compiler.rs+`
+|Bytecode |`+src/vm/bytecode.rs+`
+|VM |`+src/vm/machine.rs+`
+|Optimizer |`+src/vm/optimizer.rs+`
+|WASM Compiler |`+src/codegen/wasm.rs+`
+|===
+
+'''''
+
+=== References
+
+[arabic]
+. Leroy, X. (2009). "`Formal Verification of a Realistic Compiler`"
+(CompCert)
+. Kumar, R. et al. (2014). "`CakeML: A Verified Implementation of ML`"
+. Appel, A.W. (2011). "`Verified Software Toolchain`"
+. Chlipala, A. (2017). "`Formal Reasoning About Programs`"
diff --git a/docs/proofs/compiler/semantic-preservation.md b/docs/proofs/compiler/semantic-preservation.md
deleted file mode 100644
index 439739a..0000000
--- a/docs/proofs/compiler/semantic-preservation.md
+++ /dev/null
@@ -1,511 +0,0 @@
-
-# WokeLang Compiler Correctness Proofs
-
-This document provides formal proofs of semantic preservation across WokeLang's compilation stages: Source → AST → Bytecode → WASM.
-
-## 1. Compilation Pipeline
-
-```
-Source Code (.woke)
- │
- ▼ Lexer (tokenize)
- Tokens
- │
- ▼ Parser (parse)
- AST
- │
- ├──────────────────────┐
- │ │
- ▼ ▼
- Interpreter Bytecode Compiler
- (tree-walk) │
- │ ▼
- │ Bytecode
- │ │
- │ ▼
- │ VM
- │ │
- │ │
- ▼ ▼
- Result₁ Result₂
-
- │
- └───────► WASM Compiler
- │
- ▼
- WASM Binary
- │
- ▼
- WASM Runtime
- │
- ▼
- Result₃
-```
-
-**Main Theorem (Compiler Correctness):** For all well-typed programs P:
-```
-interpret(P) = run_vm(compile_bytecode(P)) = run_wasm(compile_wasm(P))
-```
-
----
-
-## 2. Lexer Correctness
-
-### 2.1 Lexer Specification
-
-```
-tokenize : String → Result, LexError>
-```
-
-### 2.2 Lexer Properties
-
-**Theorem 2.1 (Lexer Totality):** For any input string s, `tokenize(s)` terminates.
-
-**Proof:** The logos-based lexer processes input character by character with finite automata. Each character advances the position. □
-
-**Theorem 2.2 (Lexer Determinism):** For any input s, tokenize(s) produces a unique result.
-
-**Proof:** DFA-based tokenization is deterministic by construction. □
-
-**Theorem 2.3 (Token Preservation):** `concat(map(token_text, tokenize(s))) = s` (modulo whitespace)
-
-**Proof:** Each token records its span in the source. Concatenating spans recovers the original input. □
-
-### 2.3 Token Classification Correctness
-
-**Lemma 2.1 (Keyword Recognition):** All reserved keywords are correctly classified.
-
-```
-∀s ∈ Keywords. tokenize(s) = [Token::Keyword(s)]
-```
-
-**Proof:** The Token enum in `token.rs` explicitly matches all keywords from the grammar. □
-
----
-
-## 3. Parser Correctness
-
-### 3.1 Parser Specification
-
-```
-parse : List → Result
-```
-
-### 3.2 Grammar Conformance
-
-**Theorem 3.1 (Grammar Soundness):** If `parse(tokens) = Ok(ast)`, then ast conforms to the EBNF grammar.
-
-**Proof:** The recursive descent parser directly encodes the EBNF production rules:
-- `parse_program()` implements `program = { top_level_item }`
-- `parse_function()` implements `function_def = ...`
-- `parse_expression()` implements the expression grammar with correct precedence
-
-Each parse function returns an AST node matching the corresponding grammar production. □
-
-**Theorem 3.2 (Grammar Completeness):** If a token sequence is valid according to the EBNF grammar, then `parse(tokens) = Ok(ast)`.
-
-**Proof:** The parser handles all grammar productions. Error recovery is not implemented, so any valid input is accepted. □
-
-### 3.3 Precedence Correctness
-
-**Theorem 3.3 (Operator Precedence):** The parser produces ASTs respecting the defined operator precedence.
-
-Precedence levels (lowest to highest):
-```
-1. or
-2. and
-3. == !=
-4. < > <= >=
-5. + -
-6. * / %
-7. - not (unary prefix)
-8. ? () [] (postfix)
-```
-
-**Proof:** The Pratt parser in `parse_expression_bp()` uses binding powers:
-```rust
-fn prefix_binding_power(op: &UnaryOp) -> u8 { 7 }
-fn infix_binding_power(op: &BinaryOp) -> (u8, u8) {
- match op {
- Or => (1, 2),
- And => (3, 4),
- Eq | NotEq => (5, 6),
- Lt | Gt | LtEq | GtEq => (7, 8),
- Add | Sub => (9, 10),
- Mul | Div | Mod => (11, 12),
- }
-}
-```
-Higher numbers bind tighter. Left-associative operators have left BP < right BP. □
-
-### 3.4 AST Well-Formedness
-
-**Invariant 3.1 (Span Validity):** All AST nodes have valid source spans.
-
-```
-∀node ∈ AST. node.span.start ≤ node.span.end ∧ node.span.end ≤ source.len()
-```
-
-**Invariant 3.2 (Tree Structure):** The AST forms a proper tree (no cycles, single root).
-
----
-
-## 4. Interpreter ↔ Bytecode VM Equivalence
-
-### 4.1 Compilation Function
-
-```
-compile : AST → CompiledProgram
-```
-
-### 4.2 Value Correspondence
-
-The interpreter and VM use the same Value type:
-```rust
-pub enum Value {
- Int(i64),
- Float(f64),
- String(String),
- Bool(bool),
- Unit,
- Array(Vec),
- Okay(Box),
- Oops(String),
- Record(HashMap),
-}
-```
-
-**Lemma 4.1 (Value Isomorphism):** Interpreter values and VM values are identical.
-
-### 4.3 Environment Correspondence
-
-**Definition:** Environment correspondence `ρ ≈ᵥₘ (stack, locals, globals)`:
-
-```
-ρ(x) = v ⟺ (x is local i → stack[base + i] = v)
- ∧ (x is global → globals[x] = v)
-```
-
-### 4.4 Compilation Correctness Lemmas
-
-**Lemma 4.2 (Expression Compilation):** For expression e with `Γ ⊢ e : τ`:
-
-```
-If ⟨e, ρ, Φ⟩ ⇓ v and ρ ≈ᵥₘ (stack, locals, globals)
-Then executing compile(e) results in stack' where top(stack') = v
-```
-
-**Proof by structural induction on e:**
-
-**Case e = n (integer literal):**
-- compile(n) = [Const(idx)] where constants[idx] = n
-- VM: push(constants[idx]) = push(n) ✓
-
-**Case e = x (variable):**
-- compile(x) = [LoadLocal(i)] if x is local
-- VM: push(stack[base + i]) = push(ρ(x)) ✓
-
-**Case e = e₁ + e₂:**
-- compile(e₁ + e₂) = compile(e₁); compile(e₂); Add
-- By IH: after compile(e₁), stack has v₁ on top
-- By IH: after compile(e₂), stack has v₂ on top (v₁ below)
-- After Add: top = v₁ + v₂ ✓
-
-**Case e = f(e₁,...,eₙ):**
-- compile(f(args)) = compile(e₁); ...; compile(eₙ); Call(n)
-- By IH: stack has [v₁, ..., vₙ] on top
-- Call creates new frame, executes f's body
-- Return pops frame, leaves result on stack ✓
-
-**Lemma 4.3 (Statement Compilation):** For statement s:
-
-```
-If ⟨s, ρ, Φ, C⟩ ⇓ᵇ (result, ρ', C') and ρ ≈ᵥₘ σ
-Then executing compile(s) from σ reaches σ' where ρ' ≈ᵥₘ σ'
-```
-
-**Proof by case analysis on s:**
-
-**Case s = remember x = e:**
-- compile(s) = compile(e); StoreLocal(i)
-- e evaluates to v (by expression lemma)
-- StoreLocal stores v at local slot i
-- New environment ρ[x ↦ v] corresponds to updated stack ✓
-
-**Case s = when e { s₁ } otherwise { s₂ }:**
-```
-compile(s) = compile(e)
- JumpIfFalse(else_label)
- compile(s₁)
- Jump(end_label)
- else_label:
- compile(s₂)
- end_label:
-```
-- If e evaluates to true: execute s₁ (by IH)
-- If e evaluates to false: jump to else_label, execute s₂ (by IH) ✓
-
-**Case s = repeat e times { body }:**
-```
-compile(s) = compile(e)
- StoreLocal(count)
- loop_start:
- LoadLocal(count)
- Const(0)
- Le
- JumpIfTrue(loop_end)
- compile(body)
- LoadLocal(count)
- Const(1)
- Sub
- StoreLocal(count)
- Jump(loop_start)
- loop_end:
-```
-- Loop executes body n times, matching interpreter semantics ✓
-
-### 4.5 Main Theorem (Interpreter-VM Equivalence)
-
-**Theorem 4.1:** For any well-typed program P:
-
-```
-interpret(P) = run_vm(compile(P))
-```
-
-**Proof:**
-1. Both start with empty environment/stack
-2. Both collect function definitions first
-3. Both execute main() if present
-4. By Lemmas 4.2 and 4.3, each step preserves correspondence
-5. Final results are identical □
-
----
-
-## 5. Bytecode → WASM Correctness
-
-### 5.1 WASM Compilation
-
-```
-compile_wasm : AST → Vec (WASM binary)
-```
-
-### 5.2 WASM Value Mapping
-
-```
-wasm_value(Int(n)) = i64.const n
-wasm_value(Float(f)) = f64.const f -- Note: current impl uses i64 for all
-wasm_value(Bool(true)) = i64.const 1
-wasm_value(Bool(false)) = i64.const 0
-```
-
-### 5.3 Instruction Correspondence
-
-| Bytecode | WASM |
-|----------|------|
-| Const(n) | i64.const n |
-| Add | i64.add |
-| Sub | i64.sub |
-| Mul | i64.mul |
-| Div | i64.div_s |
-| Mod | i64.rem_s |
-| Eq | i64.eq |
-| Lt | i64.lt_s |
-| Gt | i64.gt_s |
-| And | i64.and |
-| Or | i64.or |
-| Not | i64.eqz |
-| LoadLocal(i) | local.get i |
-| StoreLocal(i) | local.set i |
-| Jump(t) | br t |
-| JumpIfFalse(t) | br_if t (with condition negation) |
-| Call(n) | call n |
-| Return | return |
-
-### 5.4 Control Flow Translation
-
-**Lemma 5.1 (Conditional Translation):**
-```
-compile_wasm(when e { s₁ } otherwise { s₂ }) =
- compile_wasm(e)
- if (result i64)
- compile_wasm(s₁)
- else
- compile_wasm(s₂)
- end
-```
-
-**Lemma 5.2 (Loop Translation):**
-```
-compile_wasm(repeat n times { body }) =
- compile_wasm(n)
- local.set $count
- block $exit
- loop $cont
- local.get $count
- i64.const 0
- i64.le_s
- br_if $exit
- compile_wasm(body)
- local.get $count
- i64.const 1
- i64.sub
- local.set $count
- br $cont
- end
- end
-```
-
-### 5.5 WASM Correctness Theorem
-
-**Theorem 5.1 (WASM Semantic Preservation):** For pure numeric functions f:
-
-```
-interpret(f(args)) = wasm_run(compile_wasm(f), args)
-```
-
-**Proof Sketch:**
-1. WASM is a stack machine like the bytecode VM
-2. i64 arithmetic matches Rust's i64 (two's complement)
-3. Control flow blocks map directly
-4. Local variables map to WASM locals □
-
-### 5.6 WASM Limitations
-
-**TODO:** The current WASM compiler has limitations:
-- Strings not fully supported (need memory allocation)
-- Arrays not supported
-- Workers not supported
-- Consent blocks skipped
-
-These are marked as `CompileError::Unsupported` in the implementation.
-
----
-
-## 6. Optimization Correctness
-
-### 6.1 Bytecode Optimizer
-
-The optimizer in `vm/optimizer.rs` performs:
-- Dead code elimination
-- Constant folding
-- Peephole optimizations
-
-### 6.2 Optimization Soundness
-
-**Theorem 6.1 (Optimization Soundness):** For any optimization O:
-
-```
-run_vm(optimize(compile(P))) = run_vm(compile(P))
-```
-
-**Proof approach:** Each optimization rule must preserve observable behavior:
-
-**Constant Folding:**
-```
-Const(a); Const(b); Add → Const(a + b)
-```
-Preserved because a + b at compile time = a + b at runtime.
-
-**Dead Code Elimination:**
-```
-Const(c); Pop → ε (if c has no side effects)
-```
-Preserved because the value is discarded anyway.
-
-**TODO:** Formal proof of each optimization rule.
-
----
-
-## 7. Type Preservation Across Compilation
-
-### 7.1 Typed Bytecode
-
-**Definition:** A bytecode instruction sequence is well-typed if:
-- Stack effects are balanced
-- Types at each point are consistent
-
-### 7.2 Compilation Preserves Types
-
-**Theorem 7.1:** If `Γ ⊢ e : τ` then `compile(e)` produces bytecode with stack effect `[] → [τ]`.
-
-**Proof:** By structural induction, matching each typing rule to its compilation:
-- T-Int: Const(n) has effect [] → [Int] ✓
-- T-Add-Int: compile(e₁); compile(e₂); Add has effect [] → [Int]; [] → [Int]; [Int,Int] → [Int] = [] → [Int] ✓
-- etc. □
-
----
-
-## 8. End-to-End Correctness
-
-### 8.1 Full Pipeline Theorem
-
-**Theorem 8.1 (End-to-End Correctness):** For the full compilation pipeline:
-
-```
-∀P. well_typed(P) →
- ∀input. denotation(P)(input) = execution(compile(P))(input)
-```
-
-Where:
-- `denotation(P)` is the denotational semantics of P
-- `execution(compile(P))` is running compiled code
-
-**Proof:**
-1. By adequacy theorem (denotational ↔ operational)
-2. By interpreter correctness (operational ↔ interpreter)
-3. By VM equivalence (interpreter ↔ VM)
-4. By WASM correctness (VM ↔ WASM for supported features)
-□
-
----
-
-## 9. Verified Compilation Approach
-
-### 9.1 Future Work: Verified Compiler
-
-To achieve full formal verification, implement:
-
-1. **Compiler in Coq/Lean** with extracted Rust code
-2. **CompCert-style** simulation relations
-3. **Verified WASM backend** using wasm-verified
-
-### 9.2 Current Verification Status
-
-| Component | Verification Level |
-|-----------|-------------------|
-| Lexer | Tested, not proven |
-| Parser | Tested, not proven |
-| Type Checker | Tested, algorithm correct by construction |
-| Interpreter | Reference implementation |
-| Bytecode Compiler | Correspondence tested |
-| VM | Tested against interpreter |
-| WASM Compiler | Partial, limitations documented |
-| Optimizer | Each rule should be proven |
-
----
-
-## 10. Implementation Correspondence
-
-| Proof Concept | Implementation File |
-|---------------|---------------------|
-| Lexer | `src/lexer/mod.rs`, `token.rs` |
-| Parser | `src/parser/mod.rs` |
-| AST | `src/ast/mod.rs` |
-| Interpreter | `src/interpreter/mod.rs` |
-| Bytecode Compiler | `src/vm/compiler.rs` |
-| Bytecode | `src/vm/bytecode.rs` |
-| VM | `src/vm/machine.rs` |
-| Optimizer | `src/vm/optimizer.rs` |
-| WASM Compiler | `src/codegen/wasm.rs` |
-
----
-
-## References
-
-1. Leroy, X. (2009). "Formal Verification of a Realistic Compiler" (CompCert)
-2. Kumar, R. et al. (2014). "CakeML: A Verified Implementation of ML"
-3. Appel, A.W. (2011). "Verified Software Toolchain"
-4. Chlipala, A. (2017). "Formal Reasoning About Programs"
diff --git a/docs/proofs/complexity/complexity-analysis.adoc b/docs/proofs/complexity/complexity-analysis.adoc
new file mode 100644
index 0000000..314c3f5
--- /dev/null
+++ b/docs/proofs/complexity/complexity-analysis.adoc
@@ -0,0 +1,421 @@
+== WokeLang Complexity Analysis
+
+This document provides rigorous complexity analysis of WokeLang’s core
+algorithms, runtime operations, and space usage.
+
+=== 1. Lexical Analysis Complexity
+
+==== 1.1 Tokenization
+
+*Algorithm:* DFA-based lexer (logos crate)
+
+*Time Complexity:* O(n) where n = |input|
+
+*Proof:* - Each input character is examined exactly once - DFA
+transitions are O(1) (lookup table) - Token emission is O(1) amortized
+(Vec push) - Total: O(n) □
+
+*Space Complexity:* O(n) for token storage
+
+*Proof:* - Each token stores a span (2 words) + variant tag - Maximum
+tokens ≈ n/2 (alternating single-char tokens) - Total: O(n) □
+
+==== 1.2 Token Categories
+
+[cols=",,",options="header",]
+|===
+|Token Type |Recognition Time |Examples
+|Keywords |O(k) where k = keyword length |`+remember+`, `+when+`
+|Identifiers |O(k) |`+myVariable+`
+|Integers |O(d) where d = digits |`+12345+`
+|Floats |O(d) |`+3.14159+`
+|Strings |O(s) where s = string length |`+"hello"+`
+|Operators |O(1) |`+++`, `+==+`
+|===
+
+'''''
+
+=== 2. Parsing Complexity
+
+==== 2.1 Recursive Descent Parser
+
+*Time Complexity:* O(n) where n = number of tokens
+
+*Proof:* - Each token is consumed exactly once - No backtracking in the
+grammar (LL(1)-like) - Recursive calls bounded by grammar structure -
+Expression parsing: O(tokens in expression) - Total: O(n) □
+
+==== 2.2 Pratt Parser (Expressions)
+
+*Time Complexity:* O(e) where e = expression tokens
+
+*Proof:* - Each token consumed once in prefix/infix position - Binding
+power comparisons are O(1) - AST construction is O(1) per node - Total:
+O(e) □
+
+==== 2.3 Parse Tree Size
+
+*Theorem 2.1:* The AST size is O(n) where n = input tokens.
+
+*Proof:* - Each token generates at most one AST node - Binary
+expressions: 1 node per operator - Statements: 1 node per statement - No
+AST amplification - Total nodes ≤ 2n □
+
+'''''
+
+=== 3. Type Checking Complexity
+
+==== 3.1 Type Inference (Algorithm W)
+
+*Time Complexity:* O(n² α(n)) worst case, O(n) typical
+
+Where: - n = number of type constraints - α(n) = inverse Ackermann
+function (union-find)
+
+*Proof:* - Constraint generation: O(n) (one pass over AST) -
+Unification: O(α(n)) per constraint (union-find) - Occurs check: O(type
+size) per unification - Worst case: n unifications, each O(n) occurs
+check = O(n²) - With path compression: O(n² α(n)) □
+
+*Space Complexity:* O(n) for type environment and substitutions
+
+==== 3.2 Unification
+
+*Time Complexity:* O(s₁ + s₂) where sᵢ = type size
+
+*Proof:* - Structural recursion visits each type node once - Occurs
+check is O(type size) - Substitution application is O(type size) -
+Total: O(s₁ + s₂) □
+
+==== 3.3 Practical Bounds
+
+For typical programs: - Type sizes are small (≤ 10 nodes) - Constraint
+count ~ AST size - Effective complexity: O(n) for programs of practical
+size
+
+'''''
+
+=== 4. Interpreter Complexity
+
+==== 4.1 Expression Evaluation
+
+[cols=",,",options="header",]
+|===
+|Expression |Time Complexity |Space Complexity
+|Literal |O(1) |O(1)
+|Variable |O(d) where d = scope depth |O(1)
+|Binary op |O(eval(e₁) + eval(e₂)) |O(stack depth)
+|Function call |O(eval(args) + eval(body)) |O(call depth)
+|Array literal |O(Σ eval(eᵢ)) |O(n) elements
+|Array index |O(eval(arr) + eval(idx)) |O(1)
+|===
+
+==== 4.2 Statement Execution
+
+[cols=",",options="header",]
+|===
+|Statement |Time Complexity
+|Variable decl |O(eval(expr))
+|Assignment |O(eval(expr) + lookup)
+|Conditional |O(eval(cond) + eval(branch))
+|Loop (repeat n) |O(n × eval(body))
+|Pattern match |O(eval(scrutinee) + arms × pattern_match)
+|Consent block |O(lookup) + O(body) if granted
+|===
+
+==== 4.3 Variable Lookup
+
+*Time Complexity:* O(d) where d = scope nesting depth
+
+*Proof:* - Linear search through scope chain - Each scope is a HashMap
+(O(1) lookup) - Maximum d scopes to search - Total: O(d) □
+
+*Optimization:* Could use De Bruijn indices for O(1) lookup.
+
+==== 4.4 Function Call Overhead
+
+*Time Complexity:* O(k + eval(body)) where k = arity
+
+*Breakdown:* - Parameter binding: O(k) - Scope push: O(1) - Body
+execution: O(body) - Scope pop: O(1) - Return: O(1)
+
+'''''
+
+=== 5. Bytecode Compilation Complexity
+
+==== 5.1 Compilation Pass
+
+*Time Complexity:* O(n) where n = AST nodes
+
+*Proof:* - Single pass over AST - Each node generates O(1) instructions
+(amortized) - Constant pool insertions are O(1) amortized - Jump
+patching: O(1) per jump - Total: O(n) □
+
+==== 5.2 Bytecode Size
+
+*Theorem 5.1:* Generated bytecode size is O(n) where n = AST nodes.
+
+*Proof:* - Each AST node generates bounded instructions - Literals: 1
+instruction (Const) - Binops: 1 instruction - Conditionals: 3-4
+instructions (if/else/end) - Loops: 6-7 instructions - Bounded expansion
+factor (≤ 10x) - Total: O(n) □
+
+'''''
+
+=== 6. Virtual Machine Complexity
+
+==== 6.1 Instruction Dispatch
+
+*Time Complexity:* O(1) per instruction
+
+*Implementation:* Match statement on OpCode enum (compiled to jump
+table)
+
+==== 6.2 Stack Operations
+
+[cols=",,",options="header",]
+|===
+|Operation |Time |Space
+|Push |O(1) amortized |O(1)
+|Pop |O(1) |O(1)
+|Peek |O(1) |O(1)
+|Dup |O(1) |O(1)
+|LoadLocal |O(1) |O(1)
+|StoreLocal |O(1) |O(1)
+|===
+
+==== 6.3 Function Calls
+
+*Time Complexity:* O(k + 1) where k = arity
+
+*Breakdown:* - Create call frame: O(1) - Reserve locals: O(locals -
+arity) - Push to call stack: O(1)
+
+==== 6.4 Overall VM Execution
+
+*Time Complexity:* O(instructions executed)
+
+*Theorem 6.1:* For a program P with i instructions executed:
+
+....
+T(P) = O(i)
+....
+
+*Space Complexity:* O(max_stack + max_call_depth × frame_size)
+
+'''''
+
+=== 7. WASM Compilation Complexity
+
+==== 7.1 Compilation Time
+
+*Time Complexity:* O(n) where n = AST nodes
+
+*Proof:* - Single pass over AST - WASM instruction emission is O(1) -
+Section construction is O(functions) - Binary encoding is O(output size)
+- Total: O(n) □
+
+==== 7.2 Output Size
+
+*WASM Binary Size:* O(n) where n = source size
+
+*Breakdown:* - Type section: O(functions) - Function section:
+O(functions) - Export section: O(exported items) - Code section:
+O(instructions)
+
+'''''
+
+=== 8. Security System Complexity
+
+==== 8.1 Capability Lookup
+
+*Time Complexity:* O(c) where c = capabilities per scope
+
+*Implementation:* HashMap lookup + linear scan of capability list
+
+*Optimization:* Could use HashSet for O(1) average.
+
+==== 8.2 Consent Store
+
+[cols=",,",options="header",]
+|===
+|Operation |Time |Space
+|Check |O(1) HashMap lookup |O(1)
+|Record |O(1) HashMap insert |O(1)
+|Load |O(c) where c = stored consents |O(c)
+|Save |O(c) |O(c)
+|===
+
+==== 8.3 Audit Log
+
+*Time Complexity:* O(1) per entry (append)
+
+*Space Complexity:* O(e) where e = events
+
+'''''
+
+=== 9. Standard Library Complexity
+
+==== 9.1 Math Functions
+
+[cols=",,",options="header",]
+|===
+|Function |Time |Notes
+|abs |O(1) |
+|sqrt |O(1) |Hardware instruction
+|pow |O(log exp) |Exponentiation by squaring
+|sin/cos/tan |O(1) |Taylor series (bounded iterations)
+|floor/ceil/round |O(1) |
+|min/max |O(1) |
+|random |O(1) |PRNG
+|===
+
+==== 9.2 String Operations
+
+[cols=",",options="header",]
+|===
+|Operation |Time
+|len |O(1) (cached)
+|concat |O(n + m)
+|substring |O(k) where k = substring length
+|indexOf |O(n × m) naive, O(n + m) with KMP
+|===
+
+==== 9.3 Array Operations
+
+[cols=",",options="header",]
+|===
+|Operation |Time
+|len |O(1)
+|index |O(1)
+|push |O(1) amortized
+|pop |O(1)
+|concat |O(n + m)
+|map |O(n × f) where f = function cost
+|filter |O(n × p) where p = predicate cost
+|reduce |O(n × f)
+|===
+
+==== 9.4 I/O Operations
+
+[cols=",,",options="header",]
+|===
+|Operation |Time |Notes
+|readFile |O(file size) |Disk I/O bound
+|writeFile |O(data size) |Disk I/O bound
+|readLine |O(line length) |Blocking
+|print |O(output length) |
+|===
+
+==== 9.5 JSON Operations
+
+[cols=",,",options="header",]
+|===
+|Operation |Time |Space
+|parse |O(n) |O(n)
+|stringify |O(n) |O(n)
+|get (path) |O(path length) |O(1)
+|set (path) |O(n) deep copy |O(n)
+|===
+
+'''''
+
+=== 10. Asymptotic Bounds Summary
+
+==== 10.1 Compilation Pipeline
+
+[cols=",,",options="header",]
+|===
+|Phase |Time |Space
+|Lexing |O(n) |O(n)
+|Parsing |O(n) |O(n)
+|Type Checking |O(n²) worst, O(n) typical |O(n)
+|Bytecode Compilation |O(n) |O(n)
+|WASM Compilation |O(n) |O(n)
+|*Total* |*O(n²)* worst, *O(n)* typical |*O(n)*
+|===
+
+==== 10.2 Runtime
+
+[cols=",",options="header",]
+|===
+|Operation |Time
+|Instruction execution |O(1)
+|Variable lookup |O(d) scope depth
+|Function call |O(arity)
+|Loop iteration |O(1) overhead
+|Pattern match |O(patterns)
+|===
+
+==== 10.3 Memory Usage
+
+[cols=",",options="header",]
+|===
+|Component |Space
+|Value stack |O(max depth)
+|Call stack |O(max recursion)
+|Environment |O(variables)
+|Constants |O(unique literals)
+|Heap (arrays/strings) |O(data size)
+|===
+
+'''''
+
+=== 11. Comparison with Other Languages
+
+==== 11.1 Compilation Time
+
+[cols=",",options="header",]
+|===
+|Language |Compilation Complexity
+|WokeLang |O(n) - O(n²)
+|Python |O(n) (bytecode)
+|JavaScript |O(n) (JIT baseline)
+|Rust |O(n³) (borrow checking)
+|Haskell |O(n × 2^k) (type inference with polymorphism)
+|===
+
+==== 11.2 Runtime Performance
+
+[cols=",",options="header",]
+|===
+|Language |Interpretation Overhead
+|WokeLang (tree-walk) |~100x native
+|WokeLang (bytecode) |~20x native
+|WokeLang (WASM) |~2-5x native
+|Python |~50x native
+|Lua |~10x native
+|===
+
+'''''
+
+=== 12. Optimization Opportunities
+
+==== 12.1 Identified Optimizations
+
+[arabic]
+. *Variable lookup:* Use De Bruijn indices → O(1)
+. *Type inference:* Incremental checking → O(Δn)
+. *Bytecode:* Superinstructions → fewer dispatches
+. *JIT compilation:* Hot path optimization → native speed
+
+==== 12.2 Memory Optimizations
+
+[arabic]
+. *String interning:* Deduplicate string literals
+. *Small value optimization:* Inline small arrays
+. *Compact Value representation:* NaN-boxing for 64-bit values
+. *Garbage collection:* Currently using Rust ownership; could add GC for
+cycles
+
+'''''
+
+=== References
+
+[arabic]
+. Aho, A.V. et al. (2006). "`Compilers: Principles, Techniques, and
+Tools`" (Dragon Book)
+. Appel, A.W. (1998). "`Modern Compiler Implementation in ML`"
+. Jones, R. et al. (2016). "`The Garbage Collection Handbook`"
+. Leroy, X. (1990). "`The ZINC experiment: an economical implementation
+of the ML language`"
diff --git a/docs/proofs/complexity/complexity-analysis.md b/docs/proofs/complexity/complexity-analysis.md
deleted file mode 100644
index 5115f5f..0000000
--- a/docs/proofs/complexity/complexity-analysis.md
+++ /dev/null
@@ -1,425 +0,0 @@
-
-# WokeLang Complexity Analysis
-
-This document provides rigorous complexity analysis of WokeLang's core algorithms, runtime operations, and space usage.
-
-## 1. Lexical Analysis Complexity
-
-### 1.1 Tokenization
-
-**Algorithm:** DFA-based lexer (logos crate)
-
-**Time Complexity:** O(n) where n = |input|
-
-**Proof:**
-- Each input character is examined exactly once
-- DFA transitions are O(1) (lookup table)
-- Token emission is O(1) amortized (Vec push)
-- Total: O(n) □
-
-**Space Complexity:** O(n) for token storage
-
-**Proof:**
-- Each token stores a span (2 words) + variant tag
-- Maximum tokens ≈ n/2 (alternating single-char tokens)
-- Total: O(n) □
-
-### 1.2 Token Categories
-
-| Token Type | Recognition Time | Examples |
-|------------|------------------|----------|
-| Keywords | O(k) where k = keyword length | `remember`, `when` |
-| Identifiers | O(k) | `myVariable` |
-| Integers | O(d) where d = digits | `12345` |
-| Floats | O(d) | `3.14159` |
-| Strings | O(s) where s = string length | `"hello"` |
-| Operators | O(1) | `+`, `==` |
-
----
-
-## 2. Parsing Complexity
-
-### 2.1 Recursive Descent Parser
-
-**Time Complexity:** O(n) where n = number of tokens
-
-**Proof:**
-- Each token is consumed exactly once
-- No backtracking in the grammar (LL(1)-like)
-- Recursive calls bounded by grammar structure
-- Expression parsing: O(tokens in expression)
-- Total: O(n) □
-
-### 2.2 Pratt Parser (Expressions)
-
-**Time Complexity:** O(e) where e = expression tokens
-
-**Proof:**
-- Each token consumed once in prefix/infix position
-- Binding power comparisons are O(1)
-- AST construction is O(1) per node
-- Total: O(e) □
-
-### 2.3 Parse Tree Size
-
-**Theorem 2.1:** The AST size is O(n) where n = input tokens.
-
-**Proof:**
-- Each token generates at most one AST node
-- Binary expressions: 1 node per operator
-- Statements: 1 node per statement
-- No AST amplification
-- Total nodes ≤ 2n □
-
----
-
-## 3. Type Checking Complexity
-
-### 3.1 Type Inference (Algorithm W)
-
-**Time Complexity:** O(n² α(n)) worst case, O(n) typical
-
-Where:
-- n = number of type constraints
-- α(n) = inverse Ackermann function (union-find)
-
-**Proof:**
-- Constraint generation: O(n) (one pass over AST)
-- Unification: O(α(n)) per constraint (union-find)
-- Occurs check: O(type size) per unification
-- Worst case: n unifications, each O(n) occurs check = O(n²)
-- With path compression: O(n² α(n)) □
-
-**Space Complexity:** O(n) for type environment and substitutions
-
-### 3.2 Unification
-
-**Time Complexity:** O(s₁ + s₂) where sᵢ = type size
-
-**Proof:**
-- Structural recursion visits each type node once
-- Occurs check is O(type size)
-- Substitution application is O(type size)
-- Total: O(s₁ + s₂) □
-
-### 3.3 Practical Bounds
-
-For typical programs:
-- Type sizes are small (≤ 10 nodes)
-- Constraint count ~ AST size
-- Effective complexity: O(n) for programs of practical size
-
----
-
-## 4. Interpreter Complexity
-
-### 4.1 Expression Evaluation
-
-| Expression | Time Complexity | Space Complexity |
-|------------|-----------------|------------------|
-| Literal | O(1) | O(1) |
-| Variable | O(d) where d = scope depth | O(1) |
-| Binary op | O(eval(e₁) + eval(e₂)) | O(stack depth) |
-| Function call | O(eval(args) + eval(body)) | O(call depth) |
-| Array literal | O(Σ eval(eᵢ)) | O(n) elements |
-| Array index | O(eval(arr) + eval(idx)) | O(1) |
-
-### 4.2 Statement Execution
-
-| Statement | Time Complexity |
-|-----------|-----------------|
-| Variable decl | O(eval(expr)) |
-| Assignment | O(eval(expr) + lookup) |
-| Conditional | O(eval(cond) + eval(branch)) |
-| Loop (repeat n) | O(n × eval(body)) |
-| Pattern match | O(eval(scrutinee) + arms × pattern_match) |
-| Consent block | O(lookup) + O(body) if granted |
-
-### 4.3 Variable Lookup
-
-**Time Complexity:** O(d) where d = scope nesting depth
-
-**Proof:**
-- Linear search through scope chain
-- Each scope is a HashMap (O(1) lookup)
-- Maximum d scopes to search
-- Total: O(d) □
-
-**Optimization:** Could use De Bruijn indices for O(1) lookup.
-
-### 4.4 Function Call Overhead
-
-**Time Complexity:** O(k + eval(body)) where k = arity
-
-**Breakdown:**
-- Parameter binding: O(k)
-- Scope push: O(1)
-- Body execution: O(body)
-- Scope pop: O(1)
-- Return: O(1)
-
----
-
-## 5. Bytecode Compilation Complexity
-
-### 5.1 Compilation Pass
-
-**Time Complexity:** O(n) where n = AST nodes
-
-**Proof:**
-- Single pass over AST
-- Each node generates O(1) instructions (amortized)
-- Constant pool insertions are O(1) amortized
-- Jump patching: O(1) per jump
-- Total: O(n) □
-
-### 5.2 Bytecode Size
-
-**Theorem 5.1:** Generated bytecode size is O(n) where n = AST nodes.
-
-**Proof:**
-- Each AST node generates bounded instructions
-- Literals: 1 instruction (Const)
-- Binops: 1 instruction
-- Conditionals: 3-4 instructions (if/else/end)
-- Loops: 6-7 instructions
-- Bounded expansion factor (≤ 10x)
-- Total: O(n) □
-
----
-
-## 6. Virtual Machine Complexity
-
-### 6.1 Instruction Dispatch
-
-**Time Complexity:** O(1) per instruction
-
-**Implementation:** Match statement on OpCode enum (compiled to jump table)
-
-### 6.2 Stack Operations
-
-| Operation | Time | Space |
-|-----------|------|-------|
-| Push | O(1) amortized | O(1) |
-| Pop | O(1) | O(1) |
-| Peek | O(1) | O(1) |
-| Dup | O(1) | O(1) |
-| LoadLocal | O(1) | O(1) |
-| StoreLocal | O(1) | O(1) |
-
-### 6.3 Function Calls
-
-**Time Complexity:** O(k + 1) where k = arity
-
-**Breakdown:**
-- Create call frame: O(1)
-- Reserve locals: O(locals - arity)
-- Push to call stack: O(1)
-
-### 6.4 Overall VM Execution
-
-**Time Complexity:** O(instructions executed)
-
-**Theorem 6.1:** For a program P with i instructions executed:
-```
-T(P) = O(i)
-```
-
-**Space Complexity:** O(max_stack + max_call_depth × frame_size)
-
----
-
-## 7. WASM Compilation Complexity
-
-### 7.1 Compilation Time
-
-**Time Complexity:** O(n) where n = AST nodes
-
-**Proof:**
-- Single pass over AST
-- WASM instruction emission is O(1)
-- Section construction is O(functions)
-- Binary encoding is O(output size)
-- Total: O(n) □
-
-### 7.2 Output Size
-
-**WASM Binary Size:** O(n) where n = source size
-
-**Breakdown:**
-- Type section: O(functions)
-- Function section: O(functions)
-- Export section: O(exported items)
-- Code section: O(instructions)
-
----
-
-## 8. Security System Complexity
-
-### 8.1 Capability Lookup
-
-**Time Complexity:** O(c) where c = capabilities per scope
-
-**Implementation:** HashMap lookup + linear scan of capability list
-
-**Optimization:** Could use HashSet for O(1) average.
-
-### 8.2 Consent Store
-
-| Operation | Time | Space |
-|-----------|------|-------|
-| Check | O(1) HashMap lookup | O(1) |
-| Record | O(1) HashMap insert | O(1) |
-| Load | O(c) where c = stored consents | O(c) |
-| Save | O(c) | O(c) |
-
-### 8.3 Audit Log
-
-**Time Complexity:** O(1) per entry (append)
-
-**Space Complexity:** O(e) where e = events
-
----
-
-## 9. Standard Library Complexity
-
-### 9.1 Math Functions
-
-| Function | Time | Notes |
-|----------|------|-------|
-| abs | O(1) | |
-| sqrt | O(1) | Hardware instruction |
-| pow | O(log exp) | Exponentiation by squaring |
-| sin/cos/tan | O(1) | Taylor series (bounded iterations) |
-| floor/ceil/round | O(1) | |
-| min/max | O(1) | |
-| random | O(1) | PRNG |
-
-### 9.2 String Operations
-
-| Operation | Time |
-|-----------|------|
-| len | O(1) (cached) |
-| concat | O(n + m) |
-| substring | O(k) where k = substring length |
-| indexOf | O(n × m) naive, O(n + m) with KMP |
-
-### 9.3 Array Operations
-
-| Operation | Time |
-|-----------|------|
-| len | O(1) |
-| index | O(1) |
-| push | O(1) amortized |
-| pop | O(1) |
-| concat | O(n + m) |
-| map | O(n × f) where f = function cost |
-| filter | O(n × p) where p = predicate cost |
-| reduce | O(n × f) |
-
-### 9.4 I/O Operations
-
-| Operation | Time | Notes |
-|-----------|------|-------|
-| readFile | O(file size) | Disk I/O bound |
-| writeFile | O(data size) | Disk I/O bound |
-| readLine | O(line length) | Blocking |
-| print | O(output length) | |
-
-### 9.5 JSON Operations
-
-| Operation | Time | Space |
-|-----------|------|-------|
-| parse | O(n) | O(n) |
-| stringify | O(n) | O(n) |
-| get (path) | O(path length) | O(1) |
-| set (path) | O(n) deep copy | O(n) |
-
----
-
-## 10. Asymptotic Bounds Summary
-
-### 10.1 Compilation Pipeline
-
-| Phase | Time | Space |
-|-------|------|-------|
-| Lexing | O(n) | O(n) |
-| Parsing | O(n) | O(n) |
-| Type Checking | O(n²) worst, O(n) typical | O(n) |
-| Bytecode Compilation | O(n) | O(n) |
-| WASM Compilation | O(n) | O(n) |
-| **Total** | **O(n²)** worst, **O(n)** typical | **O(n)** |
-
-### 10.2 Runtime
-
-| Operation | Time |
-|-----------|------|
-| Instruction execution | O(1) |
-| Variable lookup | O(d) scope depth |
-| Function call | O(arity) |
-| Loop iteration | O(1) overhead |
-| Pattern match | O(patterns) |
-
-### 10.3 Memory Usage
-
-| Component | Space |
-|-----------|-------|
-| Value stack | O(max depth) |
-| Call stack | O(max recursion) |
-| Environment | O(variables) |
-| Constants | O(unique literals) |
-| Heap (arrays/strings) | O(data size) |
-
----
-
-## 11. Comparison with Other Languages
-
-### 11.1 Compilation Time
-
-| Language | Compilation Complexity |
-|----------|------------------------|
-| WokeLang | O(n) - O(n²) |
-| Python | O(n) (bytecode) |
-| JavaScript | O(n) (JIT baseline) |
-| Rust | O(n³) (borrow checking) |
-| Haskell | O(n × 2^k) (type inference with polymorphism) |
-
-### 11.2 Runtime Performance
-
-| Language | Interpretation Overhead |
-|----------|-------------------------|
-| WokeLang (tree-walk) | ~100x native |
-| WokeLang (bytecode) | ~20x native |
-| WokeLang (WASM) | ~2-5x native |
-| Python | ~50x native |
-| Lua | ~10x native |
-
----
-
-## 12. Optimization Opportunities
-
-### 12.1 Identified Optimizations
-
-1. **Variable lookup:** Use De Bruijn indices → O(1)
-2. **Type inference:** Incremental checking → O(Δn)
-3. **Bytecode:** Superinstructions → fewer dispatches
-4. **JIT compilation:** Hot path optimization → native speed
-
-### 12.2 Memory Optimizations
-
-1. **String interning:** Deduplicate string literals
-2. **Small value optimization:** Inline small arrays
-3. **Compact Value representation:** NaN-boxing for 64-bit values
-4. **Garbage collection:** Currently using Rust ownership; could add GC for cycles
-
----
-
-## References
-
-1. Aho, A.V. et al. (2006). "Compilers: Principles, Techniques, and Tools" (Dragon Book)
-2. Appel, A.W. (1998). "Modern Compiler Implementation in ML"
-3. Jones, R. et al. (2016). "The Garbage Collection Handbook"
-4. Leroy, X. (1990). "The ZINC experiment: an economical implementation of the ML language"
diff --git a/docs/proofs/concurrency/worker-safety.adoc b/docs/proofs/concurrency/worker-safety.adoc
new file mode 100644
index 0000000..8d53cf2
--- /dev/null
+++ b/docs/proofs/concurrency/worker-safety.adoc
@@ -0,0 +1,470 @@
+== WokeLang Concurrency and Worker System Proofs
+
+This document provides formal proofs of safety properties for WokeLang’s
+worker-based concurrency model.
+
+=== 1. Concurrency Model
+
+==== 1.1 Worker Definition
+
+....
+w ∈ Worker = {
+ name: Ident,
+ body: List,
+ state: WorkerState,
+ inbox: Queue,
+ outbox: Queue
+}
+
+WorkerState ::= Created | Running | Blocked | Completed | Failed
+....
+
+==== 1.2 Message Type
+
+....
+m ∈ Message ::= Value(v)
+ | Stop
+ | Ping
+ | Pong
+ | Named(name, v)
+....
+
+==== 1.3 System State
+
+....
+Σ ∈ SystemState = {
+ workers: Map,
+ main_thread: ThreadState,
+ global_env: Environment
+}
+....
+
+'''''
+
+=== 2. Operational Semantics for Workers
+
+==== 2.1 Worker Creation
+
+....
+ w = Worker { name: n, body: s*, state: Created, inbox: [], outbox: [] }
+────────────────────────────────────────────────────────────────────────────────────────── [W-Define]
+⟨worker n { s* }, Σ⟩ → ⟨(), Σ[workers(n) := w]⟩
+....
+
+==== 2.2 Worker Spawning
+
+....
+ Σ.workers(n) = w w.state = Created
+ w' = w[state := Running]
+─────────────────────────────────────────────────────── [W-Spawn]
+⟨spawn worker n, Σ⟩ → ⟨(), Σ[workers(n) := w']⟩
+....
+
+==== 2.3 Message Send
+
+....
+ Σ.workers(target) = w
+ w' = w[inbox := w.inbox ++ [Value(v)]]
+─────────────────────────────────────────────────────────── [W-Send]
+⟨send v to target, Σ⟩ → ⟨(), Σ[workers(target) := w']⟩
+....
+
+==== 2.4 Message Receive (Blocking)
+
+....
+ Σ.workers(source) = w w.outbox = [m | rest]
+ w' = w[outbox := rest]
+─────────────────────────────────────────────────────────────── [W-Receive]
+⟨receive from source, Σ⟩ → ⟨m.value, Σ[workers(source) := w']⟩
+....
+
+==== 2.5 Worker Execution Step
+
+....
+ Σ.workers(n) = w w.state = Running w.body = [s | rest]
+ ⟨s, w.env, Φ, C⟩ ⇓ᵇ (r, env', C')
+ w' = w[body := rest, env := env']
+───────────────────────────────────────────────────────────────────── [W-Step]
+⟨Σ⟩ →ᵥ ⟨Σ[workers(n) := w']⟩
+....
+
+==== 2.6 Worker Completion
+
+....
+ Σ.workers(n) = w w.state = Running w.body = []
+ w' = w[state := Completed]
+─────────────────────────────────────────────────────────────── [W-Complete]
+⟨Σ⟩ →ᵥ ⟨Σ[workers(n) := w']⟩
+....
+
+==== 2.7 Worker Await
+
+....
+ Σ.workers(n) = w w.state = Completed
+─────────────────────────────────────────────────────── [W-Await]
+⟨await n, Σ⟩ → ⟨(), Σ⟩
+....
+
+==== 2.8 Worker Cancel
+
+....
+ Σ.workers(n) = w w.state ∈ {Running, Blocked}
+ w' = w[state := Failed]
+───────────────────────────────────────────────────────────────── [W-Cancel]
+⟨cancel n, Σ⟩ → ⟨(), Σ[workers(n) := w']⟩
+....
+
+'''''
+
+=== 3. Safety Properties
+
+==== 3.1 Worker Isolation
+
+*Theorem 3.1 (Worker Isolation):* Workers cannot directly access each
+other’s local state.
+
+*Formal Statement:*
+
+....
+∀w₁, w₂ ∈ Σ.workers. w₁ ≠ w₂ →
+ w₁.env ∩ w₂.env = ∅ (no shared mutable state)
+....
+
+*Proof:* - Each worker has its own environment created at spawn time -
+Environments are separate HashMap instances - No references between
+worker environments exist - Communication only through message passing □
+
+==== 3.2 Message Passing Safety
+
+*Theorem 3.2 (Message Integrity):* Messages are delivered intact without
+corruption.
+
+*Proof:* - Messages are Rust enums (immutable once constructed) - MPSC
+channels provide memory-safe transfer - Clone semantics ensure receiver
+gets independent copy - No shared mutable references to message data □
+
+==== 3.3 No Data Races
+
+*Theorem 3.3 (Data Race Freedom):* The worker model is free of data
+races.
+
+*Definition:* A data race occurs when: 1. Two threads access the same
+memory location 2. At least one access is a write 3. Accesses are not
+synchronized
+
+*Proof:* - Workers have separate environments (no shared memory) -
+Message queues are synchronized (MPSC channels) - Global environment
+access is read-only after initialization - Rust’s ownership prevents
+aliased mutable references □
+
+==== 3.4 Deadlock Analysis
+
+*Theorem 3.4 (Conditional Deadlock Freedom):* Deadlock is possible only
+through cyclic wait patterns in user code.
+
+*Potential Deadlock Scenarios:* 1. Worker A waits for message from B, B
+waits for message from A 2. Main thread awaits worker that awaits main
+thread response
+
+*Current Implementation:* The current implementation runs workers
+synchronously, avoiding true concurrent deadlock. Future async
+implementation should include deadlock detection.
+
+*TODO:* Implement deadlock detection:
+
+....
+type WaitGraph = Map>
+
+detect_deadlock(graph: WaitGraph) → Option
+ // Tarjan's algorithm for cycle detection
+....
+
+'''''
+
+=== 4. Liveness Properties
+
+==== 4.1 Progress
+
+*Theorem 4.1 (Worker Progress):* A running worker with non-empty body
+will eventually execute or block.
+
+*Proof:* - [W-Step] applies when body is non-empty - Each statement
+either completes or blocks on I/O - No infinite internal loops without
+progress - Eventual [W-Complete] when body exhausted □
+
+==== 4.2 Message Delivery
+
+*Theorem 4.2 (Eventually Delivered):* Sent messages are eventually
+received or available.
+
+*Proof:* - [W-Send] atomically enqueues message - Queue is unbounded (in
+current implementation) - [W-Receive] dequeues when queue non-empty - No
+message loss mechanism exists □
+
+*Note:* Unbounded queues can lead to memory exhaustion. Production
+systems should bound queue size.
+
+==== 4.3 Termination
+
+*Theorem 4.3 (Conditional Termination):* Workers terminate if: 1. Body
+contains no infinite loops 2. All blocking operations eventually unblock
+
+*Proof:* - Body is a finite list of statements - Each statement either
+terminates or blocks - If blocked, external event unblocks (message
+arrival, cancel) - Eventually body is exhausted → [W-Complete] □
+
+'''''
+
+=== 5. Communication Patterns
+
+==== 5.1 Request-Response
+
+....
+// Main thread
+send request to worker;
+remember response = receive from worker;
+
+// Worker
+remember req = receive from main;
+remember result = process(req);
+send result to main;
+....
+
+*Property:* This pattern is deadlock-free if worker always responds.
+
+==== 5.2 Pipeline
+
+....
+worker stage1 { ... send to stage2; }
+worker stage2 { ... send to stage3; }
+worker stage3 { ... send to output; }
+
+spawn worker stage1;
+spawn worker stage2;
+spawn worker stage3;
+send input to stage1;
+remember result = receive from output;
+....
+
+*Property:* Pipeline is deadlock-free (unidirectional flow).
+
+==== 5.3 Worker Pool
+
+....
+// Pool of workers processing tasks
+worker processor {
+ repeat forever {
+ remember task = receive from dispatcher;
+ remember result = process(task);
+ send result to collector;
+ }
+}
+....
+
+*Property:* Pool provides load balancing; individual workers may starve.
+
+'''''
+
+=== 6. Memory Safety
+
+==== 6.1 Message Ownership
+
+*Theorem 6.1 (Message Ownership Transfer):* Sending a message transfers
+ownership to the receiver.
+
+*Proof:* - Rust’s ownership system enforces move semantics - Sender
+cannot access message after send - Receiver becomes sole owner - No
+use-after-send possible □
+
+==== 6.2 Worker Cleanup
+
+*Theorem 6.2 (Resource Cleanup):* Worker resources are released when
+worker completes or is cancelled.
+
+*Proof:* - Worker struct dropped when removed from workers map - Rust’s
+Drop trait ensures cleanup - Inbox/outbox queues freed - Environment
+dropped □
+
+==== 6.3 Channel Safety
+
+*MPSC Channel Properties:* - Sender end cloneable (multiple producers) -
+Receiver end not cloneable (single consumer) - Channel dropped when all
+senders dropped - Receiving from closed channel returns None
+
+'''''
+
+=== 7. Scheduling
+
+==== 7.1 Current Implementation (Synchronous)
+
+....
+spawn worker n; // Immediately executes n to completion
+....
+
+*Properties:* - Deterministic execution order - No preemption - No true
+parallelism - Simple to reason about
+
+==== 7.2 Future Async Implementation
+
+*TODO:* Implement async workers with: 1. Task queue 2. Thread pool 3.
+Cooperative scheduling 4. Work stealing
+
+==== 7.3 Fairness
+
+*Definition:* A scheduler is fair if every ready worker eventually runs.
+
+*Current:* Trivially fair (synchronous execution)
+
+*Async TODO:* Implement round-robin or work-stealing scheduler.
+
+'''''
+
+=== 8. Formal Model (Process Algebra)
+
+==== 8.1 CSP-Style Semantics
+
+Workers as CSP processes:
+
+....
+P, Q ::= 0 (termination)
+ | a.P (action prefix)
+ | P + Q (choice)
+ | P || Q (parallel)
+ | P \ L (hiding)
+ | X (recursion variable)
+ | μX.P (recursion)
+....
+
+==== 8.2 WokeLang Worker as CSP
+
+....
+Worker(n, body) = body.Completed(n)
+
+Send(target, v) = target!v.0
+
+Receive(source) = source?x.Continue(x)
+
+System = Main || Worker₁ || Worker₂ || ...
+....
+
+==== 8.3 Traces Semantics
+
+*Definition:* A trace is a sequence of observable events.
+
+....
+Event ::= Send(worker, value)
+ | Receive(worker, value)
+ | Spawn(worker)
+ | Complete(worker)
+ | Cancel(worker)
+....
+
+*Theorem 8.1 (Trace Equivalence):* The operational semantics and CSP
+model produce equivalent traces.
+
+'''''
+
+=== 9. Actor Model Comparison
+
+==== 9.1 Similarities to Actors
+
+[cols=",,",options="header",]
+|===
+|Property |WokeLang Workers |Classic Actors
+|Isolated state |✓ |✓
+|Message passing |✓ |✓
+|Asynchronous |Partial (sync impl) |✓
+|Supervision |✗ |✓ (Erlang)
+|Location transparency |✗ |✓ (Akka)
+|===
+
+==== 9.2 Differences
+
+[arabic]
+. *Static definition:* Workers defined at compile time, not dynamic
+spawn
+. *No supervision trees:* No automatic restart on failure
+. *Explicit channels:* Send/receive name target explicitly
+. *Main thread special:* Asymmetric model
+
+'''''
+
+=== 10. Implementation Correspondence
+
+[cols=",",options="header",]
+|===
+|Concept |Implementation (`+src/worker/mod.rs+`)
+|Worker |`+Worker+` struct
+|WorkerState |`+WorkerState+` enum
+|Message |`+WorkerMessage+` enum
+|Inbox |`+mpsc::Receiver+`
+|Outbox |`+mpsc::Sender+`
+|Spawn |`+spawn()+` method
+|Send |`+send()+` method
+|Receive |`+receive()+` / `+receive_blocking()+`
+|===
+
+'''''
+
+=== 11. Known Limitations
+
+==== 11.1 Current Implementation
+
+[arabic]
+. *Synchronous execution:* Workers run sequentially, not in parallel
+. *No thread pool:* Each spawn creates a new thread
+. *No supervision:* Errors propagate to caller
+. *No timeouts:* Blocking receive waits indefinitely
+
+==== 11.2 TODO: Improvements
+
+*TODO:* Implement: 1. Async/await workers using Tokio 2. Worker
+supervision trees 3. Timeout operations 4. Bounded message queues 5.
+Deadlock detection 6. Worker monitoring/debugging
+
+'''''
+
+=== 12. Verification Approach
+
+==== 12.1 Model Checking (Future)
+
+Using SPIN or TLA+:
+
+[source,tla]
+----
+---- MODULE Workers ----
+VARIABLES workers, messages
+
+TypeInvariant ==
+ /\ workers \in [WorkerId -> WorkerState]
+ /\ messages \in Seq(Message)
+
+SafetyInvariant ==
+ \A w1, w2 \in DOMAIN workers:
+ w1 /= w2 => Disjoint(State(w1), State(w2))
+====
+----
+
+==== 12.2 Property-Based Testing
+
+[source,rust]
+----
+#[quickcheck]
+fn worker_isolation(actions: Vec) -> bool {
+ let result = simulate(actions);
+ no_shared_state_violation(result)
+}
+----
+
+'''''
+
+=== References
+
+[arabic]
+. Hewitt, C. et al. (1973). "`A Universal Modular Actor Formalism for
+Artificial Intelligence`"
+. Hoare, C.A.R. (1978). "`Communicating Sequential Processes`"
+. Armstrong, J. (2007). "`Programming Erlang: Software for a Concurrent
+World`"
+. Agha, G. (1986). "`Actors: A Model of Concurrent Computation in
+Distributed Systems`"
diff --git a/docs/proofs/concurrency/worker-safety.md b/docs/proofs/concurrency/worker-safety.md
deleted file mode 100644
index b976f64..0000000
--- a/docs/proofs/concurrency/worker-safety.md
+++ /dev/null
@@ -1,474 +0,0 @@
-
-# WokeLang Concurrency and Worker System Proofs
-
-This document provides formal proofs of safety properties for WokeLang's worker-based concurrency model.
-
-## 1. Concurrency Model
-
-### 1.1 Worker Definition
-
-```
-w ∈ Worker = {
- name: Ident,
- body: List,
- state: WorkerState,
- inbox: Queue,
- outbox: Queue
-}
-
-WorkerState ::= Created | Running | Blocked | Completed | Failed
-```
-
-### 1.2 Message Type
-
-```
-m ∈ Message ::= Value(v)
- | Stop
- | Ping
- | Pong
- | Named(name, v)
-```
-
-### 1.3 System State
-
-```
-Σ ∈ SystemState = {
- workers: Map,
- main_thread: ThreadState,
- global_env: Environment
-}
-```
-
----
-
-## 2. Operational Semantics for Workers
-
-### 2.1 Worker Creation
-
-```
- w = Worker { name: n, body: s*, state: Created, inbox: [], outbox: [] }
-────────────────────────────────────────────────────────────────────────────────────────── [W-Define]
-⟨worker n { s* }, Σ⟩ → ⟨(), Σ[workers(n) := w]⟩
-```
-
-### 2.2 Worker Spawning
-
-```
- Σ.workers(n) = w w.state = Created
- w' = w[state := Running]
-─────────────────────────────────────────────────────── [W-Spawn]
-⟨spawn worker n, Σ⟩ → ⟨(), Σ[workers(n) := w']⟩
-```
-
-### 2.3 Message Send
-
-```
- Σ.workers(target) = w
- w' = w[inbox := w.inbox ++ [Value(v)]]
-─────────────────────────────────────────────────────────── [W-Send]
-⟨send v to target, Σ⟩ → ⟨(), Σ[workers(target) := w']⟩
-```
-
-### 2.4 Message Receive (Blocking)
-
-```
- Σ.workers(source) = w w.outbox = [m | rest]
- w' = w[outbox := rest]
-─────────────────────────────────────────────────────────────── [W-Receive]
-⟨receive from source, Σ⟩ → ⟨m.value, Σ[workers(source) := w']⟩
-```
-
-### 2.5 Worker Execution Step
-
-```
- Σ.workers(n) = w w.state = Running w.body = [s | rest]
- ⟨s, w.env, Φ, C⟩ ⇓ᵇ (r, env', C')
- w' = w[body := rest, env := env']
-───────────────────────────────────────────────────────────────────── [W-Step]
-⟨Σ⟩ →ᵥ ⟨Σ[workers(n) := w']⟩
-```
-
-### 2.6 Worker Completion
-
-```
- Σ.workers(n) = w w.state = Running w.body = []
- w' = w[state := Completed]
-─────────────────────────────────────────────────────────────── [W-Complete]
-⟨Σ⟩ →ᵥ ⟨Σ[workers(n) := w']⟩
-```
-
-### 2.7 Worker Await
-
-```
- Σ.workers(n) = w w.state = Completed
-─────────────────────────────────────────────────────── [W-Await]
-⟨await n, Σ⟩ → ⟨(), Σ⟩
-```
-
-### 2.8 Worker Cancel
-
-```
- Σ.workers(n) = w w.state ∈ {Running, Blocked}
- w' = w[state := Failed]
-───────────────────────────────────────────────────────────────── [W-Cancel]
-⟨cancel n, Σ⟩ → ⟨(), Σ[workers(n) := w']⟩
-```
-
----
-
-## 3. Safety Properties
-
-### 3.1 Worker Isolation
-
-**Theorem 3.1 (Worker Isolation):** Workers cannot directly access each other's local state.
-
-**Formal Statement:**
-```
-∀w₁, w₂ ∈ Σ.workers. w₁ ≠ w₂ →
- w₁.env ∩ w₂.env = ∅ (no shared mutable state)
-```
-
-**Proof:**
-- Each worker has its own environment created at spawn time
-- Environments are separate HashMap instances
-- No references between worker environments exist
-- Communication only through message passing □
-
-### 3.2 Message Passing Safety
-
-**Theorem 3.2 (Message Integrity):** Messages are delivered intact without corruption.
-
-**Proof:**
-- Messages are Rust enums (immutable once constructed)
-- MPSC channels provide memory-safe transfer
-- Clone semantics ensure receiver gets independent copy
-- No shared mutable references to message data □
-
-### 3.3 No Data Races
-
-**Theorem 3.3 (Data Race Freedom):** The worker model is free of data races.
-
-**Definition:** A data race occurs when:
-1. Two threads access the same memory location
-2. At least one access is a write
-3. Accesses are not synchronized
-
-**Proof:**
-- Workers have separate environments (no shared memory)
-- Message queues are synchronized (MPSC channels)
-- Global environment access is read-only after initialization
-- Rust's ownership prevents aliased mutable references □
-
-### 3.4 Deadlock Analysis
-
-**Theorem 3.4 (Conditional Deadlock Freedom):** Deadlock is possible only through cyclic wait patterns in user code.
-
-**Potential Deadlock Scenarios:**
-1. Worker A waits for message from B, B waits for message from A
-2. Main thread awaits worker that awaits main thread response
-
-**Current Implementation:** The current implementation runs workers synchronously, avoiding true concurrent deadlock. Future async implementation should include deadlock detection.
-
-**TODO:** Implement deadlock detection:
-```
-type WaitGraph = Map>
-
-detect_deadlock(graph: WaitGraph) → Option
- // Tarjan's algorithm for cycle detection
-```
-
----
-
-## 4. Liveness Properties
-
-### 4.1 Progress
-
-**Theorem 4.1 (Worker Progress):** A running worker with non-empty body will eventually execute or block.
-
-**Proof:**
-- [W-Step] applies when body is non-empty
-- Each statement either completes or blocks on I/O
-- No infinite internal loops without progress
-- Eventual [W-Complete] when body exhausted □
-
-### 4.2 Message Delivery
-
-**Theorem 4.2 (Eventually Delivered):** Sent messages are eventually received or available.
-
-**Proof:**
-- [W-Send] atomically enqueues message
-- Queue is unbounded (in current implementation)
-- [W-Receive] dequeues when queue non-empty
-- No message loss mechanism exists □
-
-**Note:** Unbounded queues can lead to memory exhaustion. Production systems should bound queue size.
-
-### 4.3 Termination
-
-**Theorem 4.3 (Conditional Termination):** Workers terminate if:
-1. Body contains no infinite loops
-2. All blocking operations eventually unblock
-
-**Proof:**
-- Body is a finite list of statements
-- Each statement either terminates or blocks
-- If blocked, external event unblocks (message arrival, cancel)
-- Eventually body is exhausted → [W-Complete] □
-
----
-
-## 5. Communication Patterns
-
-### 5.1 Request-Response
-
-```
-// Main thread
-send request to worker;
-remember response = receive from worker;
-
-// Worker
-remember req = receive from main;
-remember result = process(req);
-send result to main;
-```
-
-**Property:** This pattern is deadlock-free if worker always responds.
-
-### 5.2 Pipeline
-
-```
-worker stage1 { ... send to stage2; }
-worker stage2 { ... send to stage3; }
-worker stage3 { ... send to output; }
-
-spawn worker stage1;
-spawn worker stage2;
-spawn worker stage3;
-send input to stage1;
-remember result = receive from output;
-```
-
-**Property:** Pipeline is deadlock-free (unidirectional flow).
-
-### 5.3 Worker Pool
-
-```
-// Pool of workers processing tasks
-worker processor {
- repeat forever {
- remember task = receive from dispatcher;
- remember result = process(task);
- send result to collector;
- }
-}
-```
-
-**Property:** Pool provides load balancing; individual workers may starve.
-
----
-
-## 6. Memory Safety
-
-### 6.1 Message Ownership
-
-**Theorem 6.1 (Message Ownership Transfer):** Sending a message transfers ownership to the receiver.
-
-**Proof:**
-- Rust's ownership system enforces move semantics
-- Sender cannot access message after send
-- Receiver becomes sole owner
-- No use-after-send possible □
-
-### 6.2 Worker Cleanup
-
-**Theorem 6.2 (Resource Cleanup):** Worker resources are released when worker completes or is cancelled.
-
-**Proof:**
-- Worker struct dropped when removed from workers map
-- Rust's Drop trait ensures cleanup
-- Inbox/outbox queues freed
-- Environment dropped □
-
-### 6.3 Channel Safety
-
-**MPSC Channel Properties:**
-- Sender end cloneable (multiple producers)
-- Receiver end not cloneable (single consumer)
-- Channel dropped when all senders dropped
-- Receiving from closed channel returns None
-
----
-
-## 7. Scheduling
-
-### 7.1 Current Implementation (Synchronous)
-
-```
-spawn worker n; // Immediately executes n to completion
-```
-
-**Properties:**
-- Deterministic execution order
-- No preemption
-- No true parallelism
-- Simple to reason about
-
-### 7.2 Future Async Implementation
-
-**TODO:** Implement async workers with:
-1. Task queue
-2. Thread pool
-3. Cooperative scheduling
-4. Work stealing
-
-### 7.3 Fairness
-
-**Definition:** A scheduler is fair if every ready worker eventually runs.
-
-**Current:** Trivially fair (synchronous execution)
-
-**Async TODO:** Implement round-robin or work-stealing scheduler.
-
----
-
-## 8. Formal Model (Process Algebra)
-
-### 8.1 CSP-Style Semantics
-
-Workers as CSP processes:
-
-```
-P, Q ::= 0 (termination)
- | a.P (action prefix)
- | P + Q (choice)
- | P || Q (parallel)
- | P \ L (hiding)
- | X (recursion variable)
- | μX.P (recursion)
-```
-
-### 8.2 WokeLang Worker as CSP
-
-```
-Worker(n, body) = body.Completed(n)
-
-Send(target, v) = target!v.0
-
-Receive(source) = source?x.Continue(x)
-
-System = Main || Worker₁ || Worker₂ || ...
-```
-
-### 8.3 Traces Semantics
-
-**Definition:** A trace is a sequence of observable events.
-
-```
-Event ::= Send(worker, value)
- | Receive(worker, value)
- | Spawn(worker)
- | Complete(worker)
- | Cancel(worker)
-```
-
-**Theorem 8.1 (Trace Equivalence):** The operational semantics and CSP model produce equivalent traces.
-
----
-
-## 9. Actor Model Comparison
-
-### 9.1 Similarities to Actors
-
-| Property | WokeLang Workers | Classic Actors |
-|----------|------------------|----------------|
-| Isolated state | ✓ | ✓ |
-| Message passing | ✓ | ✓ |
-| Asynchronous | Partial (sync impl) | ✓ |
-| Supervision | ✗ | ✓ (Erlang) |
-| Location transparency | ✗ | ✓ (Akka) |
-
-### 9.2 Differences
-
-1. **Static definition:** Workers defined at compile time, not dynamic spawn
-2. **No supervision trees:** No automatic restart on failure
-3. **Explicit channels:** Send/receive name target explicitly
-4. **Main thread special:** Asymmetric model
-
----
-
-## 10. Implementation Correspondence
-
-| Concept | Implementation (`src/worker/mod.rs`) |
-|---------|---------------------------------------|
-| Worker | `Worker` struct |
-| WorkerState | `WorkerState` enum |
-| Message | `WorkerMessage` enum |
-| Inbox | `mpsc::Receiver` |
-| Outbox | `mpsc::Sender` |
-| Spawn | `spawn()` method |
-| Send | `send()` method |
-| Receive | `receive()` / `receive_blocking()` |
-
----
-
-## 11. Known Limitations
-
-### 11.1 Current Implementation
-
-1. **Synchronous execution:** Workers run sequentially, not in parallel
-2. **No thread pool:** Each spawn creates a new thread
-3. **No supervision:** Errors propagate to caller
-4. **No timeouts:** Blocking receive waits indefinitely
-
-### 11.2 TODO: Improvements
-
-**TODO:** Implement:
-1. Async/await workers using Tokio
-2. Worker supervision trees
-3. Timeout operations
-4. Bounded message queues
-5. Deadlock detection
-6. Worker monitoring/debugging
-
----
-
-## 12. Verification Approach
-
-### 12.1 Model Checking (Future)
-
-Using SPIN or TLA+:
-```tla
----- MODULE Workers ----
-VARIABLES workers, messages
-
-TypeInvariant ==
- /\ workers \in [WorkerId -> WorkerState]
- /\ messages \in Seq(Message)
-
-SafetyInvariant ==
- \A w1, w2 \in DOMAIN workers:
- w1 /= w2 => Disjoint(State(w1), State(w2))
-====
-```
-
-### 12.2 Property-Based Testing
-
-```rust
-#[quickcheck]
-fn worker_isolation(actions: Vec) -> bool {
- let result = simulate(actions);
- no_shared_state_violation(result)
-}
-```
-
----
-
-## References
-
-1. Hewitt, C. et al. (1973). "A Universal Modular Actor Formalism for Artificial Intelligence"
-2. Hoare, C.A.R. (1978). "Communicating Sequential Processes"
-3. Armstrong, J. (2007). "Programming Erlang: Software for a Concurrent World"
-4. Agha, G. (1986). "Actors: A Model of Concurrent Computation in Distributed Systems"
diff --git a/docs/proofs/formal-semantics/denotational-semantics.md b/docs/proofs/formal-semantics/denotational-semantics.adoc
similarity index 74%
rename from docs/proofs/formal-semantics/denotational-semantics.md
rename to docs/proofs/formal-semantics/denotational-semantics.adoc
index 24755f2..0751805 100644
--- a/docs/proofs/formal-semantics/denotational-semantics.md
+++ b/docs/proofs/formal-semantics/denotational-semantics.adoc
@@ -1,98 +1,94 @@
-
-# WokeLang Denotational Semantics
+== WokeLang Denotational Semantics
-This document provides the mathematical denotational semantics for WokeLang, giving precise meaning to programs as mathematical objects.
+This document provides the mathematical denotational semantics for
+WokeLang, giving precise meaning to programs as mathematical objects.
-## 1. Semantic Domains
+=== 1. Semantic Domains
-### 1.1 Base Domains
+==== 1.1 Base Domains
-```
+....
ℤ₆₄ = {-2⁶³, ..., 2⁶³-1} (64-bit signed integers)
ℝ₆₄ = IEEE 754 double precision (64-bit floats)
𝔹 = {true, false} (booleans)
𝕊 = Σ* (strings over UTF-8 alphabet Σ)
𝟙 = {unit} (unit type)
-```
+....
-### 1.2 Lifted Domains
+==== 1.2 Lifted Domains
-For any domain D, we define the lifted domain D⊥ = D ∪ {⊥} where ⊥ represents non-termination or error.
+For any domain D, we define the lifted domain D⊥ = D ∪ \{⊥} where ⊥
+represents non-termination or error.
-### 1.3 Value Domain
+==== 1.3 Value Domain
The domain of WokeLang values is defined recursively:
-```
+....
𝕍 = ℤ₆₄ + ℝ₆₄ + 𝕊 + 𝔹 + 𝟙 + 𝕍* + (𝕍 + 𝕊) + (𝕍 →ᶜ 𝕍⊥)
-```
+....
-Where:
-- `𝕍*` = finite sequences (arrays)
-- `𝕍 + 𝕊` = Result type (Okay(v) | Oops(s))
-- `𝕍 →ᶜ 𝕍⊥` = continuous functions (closures)
+Where: - `+𝕍*+` = finite sequences (arrays) - `+𝕍 + 𝕊+` = Result type
+(Okay(v) | Oops(s)) - `+𝕍 →ᶜ 𝕍⊥+` = continuous functions (closures)
-### 1.4 Environment Domain
+==== 1.4 Environment Domain
-```
+....
Env = Ident → 𝕍⊥
-```
+....
-### 1.5 Store Domain (for mutable state)
+==== 1.5 Store Domain (for mutable state)
-```
+....
Store = Loc → 𝕍⊥
-```
+....
-### 1.6 Continuation Domain
+==== 1.6 Continuation Domain
-```
+....
Cont = 𝕍 → Ans
Ans = 𝕍⊥
-```
+....
-### 1.7 Consent Domain
+==== 1.7 Consent Domain
-```
+....
Consent = ℘(Permission)
Permission = 𝕊
-```
+....
----
+'''''
-## 2. Semantic Functions
+=== 2. Semantic Functions
-### 2.1 Expression Semantics
+==== 2.1 Expression Semantics
The semantic function for expressions:
-```
+....
ℰ⟦·⟧ : Expr → Env → Consent → 𝕍⊥
-```
+....
-#### Literals
+===== Literals
-```
+....
ℰ⟦n⟧ρ C = n where n ∈ ℤ₆₄
ℰ⟦f⟧ρ C = f where f ∈ ℝ₆₄
ℰ⟦s⟧ρ C = s where s ∈ 𝕊
ℰ⟦true⟧ρ C = true
ℰ⟦false⟧ρ C = false
ℰ⟦unit⟧ρ C = unit
-```
+....
-#### Variables
+===== Variables
-```
+....
ℰ⟦x⟧ρ C = ρ(x)
-```
+....
-#### Binary Operations
+===== Binary Operations
-```
+....
ℰ⟦e₁ + e₂⟧ρ C =
let v₁ = ℰ⟦e₁⟧ρ C in
let v₂ = ℰ⟦e₂⟧ρ C in
@@ -138,11 +134,11 @@ The semantic function for expressions:
case (v₁, v₂) of
(n₁ : ℤ, n₂ : ℤ) → if n₂ = 0 then ⊥ else n₁ mod n₂
_ → ⊥
-```
+....
-#### Comparison Operations
+===== Comparison Operations
-```
+....
ℰ⟦e₁ == e₂⟧ρ C =
let v₁ = ℰ⟦e₁⟧ρ C in
let v₂ = ℰ⟦e₂⟧ρ C in
@@ -158,11 +154,11 @@ The semantic function for expressions:
(f₁ : ℝ, f₂ : ℝ) → f₁ < f₂
(s₁ : 𝕊, s₂ : 𝕊) → s₁ <ₗₑₓ s₂
_ → ⊥
-```
+....
-#### Logical Operations
+===== Logical Operations
-```
+....
ℰ⟦e₁ and e₂⟧ρ C =
let v₁ = ℰ⟦e₁⟧ρ C in
if truthy(v₁) then
@@ -176,10 +172,11 @@ The semantic function for expressions:
true
else
truthy(ℰ⟦e₂⟧ρ C)
-```
+....
-Where `truthy` is defined as:
-```
+Where `+truthy+` is defined as:
+
+....
truthy(false) = false
truthy(0) = false
truthy(0.0) = false
@@ -188,11 +185,11 @@ truthy(unit) = false
truthy([]) = false
truthy(Oops(_)) = false
truthy(_) = true
-```
+....
-#### Unary Operations
+===== Unary Operations
-```
+....
ℰ⟦-e⟧ρ C =
let v = ℰ⟦e⟧ρ C in
case v of
@@ -201,42 +198,42 @@ truthy(_) = true
_ → ⊥
ℰ⟦not e⟧ρ C = ¬truthy(ℰ⟦e⟧ρ C)
-```
+....
-#### Function Calls
+===== Function Calls
-```
+....
ℰ⟦f(e₁,...,eₙ)⟧ρ C =
let v₁ = ℰ⟦e₁⟧ρ C in
...
let vₙ = ℰ⟦eₙ⟧ρ C in
ℱ⟦f⟧(v₁,...,vₙ) C
-```
+....
-#### Arrays
+===== Arrays
-```
+....
ℰ⟦[e₁,...,eₙ]⟧ρ C =
let v₁ = ℰ⟦e₁⟧ρ C in
...
let vₙ = ℰ⟦eₙ⟧ρ C in
[v₁,...,vₙ]
-```
+....
-#### Array Indexing
+===== Array Indexing
-```
+....
ℰ⟦e₁[e₂]⟧ρ C =
let arr = ℰ⟦e₁⟧ρ C in
let idx = ℰ⟦e₂⟧ρ C in
case (arr, idx) of
([v₀,...,vₖ], n : ℤ) → if 0 ≤ n ≤ k then vₙ else ⊥
_ → ⊥
-```
+....
-#### Result Types
+===== Result Types
-```
+....
ℰ⟦Okay(e)⟧ρ C = inl(ℰ⟦e⟧ρ C)
ℰ⟦Oops(e)⟧ρ C = inr(ℰ⟦e⟧ρ C)
@@ -244,71 +241,72 @@ truthy(_) = true
case ℰ⟦e⟧ρ C of
inl(v) → v
inr(s) → ⊥
-```
+....
-#### Unit Measurement
+===== Unit Measurement
-```
+....
ℰ⟦e measured in u⟧ρ C = ℰ⟦e⟧ρ C
-```
+....
-Note: Units are currently annotations only. See Section 6 for dimensional analysis extension.
+Note: Units are currently annotations only. See Section 6 for
+dimensional analysis extension.
----
+'''''
-### 2.2 Statement Semantics
+==== 2.2 Statement Semantics
Statement semantics use a continuation-passing style:
-```
+....
𝒮⟦·⟧ : Stmt → Env → Consent → Cont → (Env × Consent × Ans)
-```
+....
-#### Variable Declaration
+===== Variable Declaration
-```
+....
𝒮⟦remember x = e⟧ρ C κ =
let v = ℰ⟦e⟧ρ C in
case v of
⊥ → (ρ, C, ⊥)
v → (ρ[x ↦ v], C, κ(unit))
-```
+....
-#### Assignment
+===== Assignment
-```
+....
𝒮⟦x = e⟧ρ C κ =
let v = ℰ⟦e⟧ρ C in
case v of
⊥ → (ρ, C, ⊥)
v → if x ∈ dom(ρ) then (ρ[x ↦ v], C, κ(unit))
else (ρ, C, ⊥)
-```
+....
-#### Return
+===== Return
-```
+....
𝒮⟦give back e⟧ρ C κ =
let v = ℰ⟦e⟧ρ C in
(ρ, C, v)
-```
+....
Note: Return ignores the continuation κ.
-#### Conditional
+===== Conditional
-```
+....
𝒮⟦when e {s₁*} otherwise {s₂*}⟧ρ C κ =
let b = ℰ⟦e⟧ρ C in
if truthy(b) then
𝒮*⟦s₁*⟧ρ C κ
else
𝒮*⟦s₂*⟧ρ C κ
-```
+....
-#### Loop
+===== Loop
-```
+....
𝒮⟦repeat e times {s*}⟧ρ C κ =
let n = ℰ⟦e⟧ρ C in
case n of
@@ -321,41 +319,41 @@ where loop(n, ρ, C, κ) =
case r of
⊥ → (ρ', C', ⊥)
_ → loop(n-1, ρ', C', κ)
-```
+....
-#### Attempt Block
+===== Attempt Block
-```
+....
𝒮⟦attempt safely {s*} or reassure msg⟧ρ C κ =
let (ρ', C', r) = 𝒮*⟦s*⟧ρ C κ in
case r of
⊥ → (ρ, C, κ(unit)) -- Error recovery
v → (ρ', C', v) -- Success
-```
+....
-#### Consent Block
+===== Consent Block
-```
+....
𝒮⟦only if okay perm {s*}⟧ρ C κ =
if perm ∈ C then
𝒮*⟦s*⟧ρ C κ
else
(ρ, C, κ(unit)) -- Silently skip if no consent
-```
+....
-#### Pattern Matching
+===== Pattern Matching
-```
+....
𝒮⟦decide based on e {p₁ → {s₁*}; ...; pₙ → {sₙ*}}⟧ρ C κ =
let v = ℰ⟦e⟧ρ C in
case firstMatch(v, [(p₁, s₁*), ..., (pₙ, sₙ*)], ρ) of
Some(bindings, s*) → 𝒮*⟦s*⟧(ρ ⊕ bindings) C κ
None → (ρ, C, κ(unit))
-```
+....
-#### Statement Sequence
+===== Statement Sequence
-```
+....
𝒮*⟦ε⟧ρ C κ = (ρ, C, κ(unit))
𝒮*⟦s; s*⟧ρ C κ =
@@ -364,26 +362,26 @@ where loop(n, ρ, C, κ) =
⊥ → (ρ', C', ⊥)
_ → if isReturn(r) then (ρ', C', r)
else 𝒮*⟦s*⟧ρ' C' κ
-```
+....
----
+'''''
-### 2.3 Function Semantics
+==== 2.3 Function Semantics
-```
+....
ℱ⟦·⟧ : FunctionDef → Env
ℱ⟦to f(x₁,...,xₙ) { body }⟧ =
λ(v₁,...,vₙ). λC.
let ρ = [x₁ ↦ v₁, ..., xₙ ↦ vₙ] in
let (_, _, r) = 𝒮*⟦body⟧ρ C (λv. v) in
r
-```
+....
----
+'''''
-### 2.4 Program Semantics
+==== 2.4 Program Semantics
-```
+....
𝒫⟦·⟧ : Program → Consent → 𝕍⊥
𝒫⟦program⟧C =
@@ -393,79 +391,82 @@ where loop(n, ρ, C, κ) =
ℱ⟦Φ("main")⟧() C'
else
unit
-```
+....
----
+'''''
-## 3. Semantic Properties
+=== 3. Semantic Properties
-### 3.1 Compositionality
+==== 3.1 Compositionality
-**Theorem 3.1:** WokeLang semantics are compositional.
+*Theorem 3.1:* WokeLang semantics are compositional.
For any expression context E[·]:
-```
+
+....
ℰ⟦E[e]⟧ρ C = ℰ⟦E⟧(ℰ⟦e⟧ρ C) ρ C
-```
+....
-### 3.2 Monotonicity
+==== 3.2 Monotonicity
-**Theorem 3.2:** All semantic functions are monotonic with respect to the information ordering ⊑ on domains.
+*Theorem 3.2:* All semantic functions are monotonic with respect to the
+information ordering ⊑ on domains.
-```
+....
If ρ₁ ⊑ ρ₂ then ℰ⟦e⟧ρ₁ C ⊑ ℰ⟦e⟧ρ₂ C
-```
+....
-### 3.3 Continuity
+==== 3.3 Continuity
-**Theorem 3.3:** All semantic functions are continuous (preserve least upper bounds of directed sets).
+*Theorem 3.3:* All semantic functions are continuous (preserve least
+upper bounds of directed sets).
This ensures that fixed-point semantics for recursion are well-defined.
-### 3.4 Adequacy
+==== 3.4 Adequacy
-**Theorem 3.4 (Computational Adequacy):** The denotational semantics agrees with operational semantics.
+*Theorem 3.4 (Computational Adequacy):* The denotational semantics
+agrees with operational semantics.
-```
+....
ℰ⟦e⟧ρ C = v ⟺ ⟨e, ρ, Φ, C⟩ ⇓ v
-```
+....
----
+'''''
-## 4. Domain Equations
+=== 4. Domain Equations
-### 4.1 Solving Recursive Domain Equations
+==== 4.1 Solving Recursive Domain Equations
The value domain 𝕍 satisfies:
-```
+....
𝕍 ≅ ℤ₆₄ + ℝ₆₄ + 𝕊 + 𝔹 + 𝟙 + 𝕍* + (𝕍 + 𝕊) + (𝕍 →ᶜ 𝕍⊥)
-```
+....
-This is solved using standard techniques:
-1. Initial algebra construction
-2. Limit of finite approximations
-3. Category-theoretic solution in CPO
+This is solved using standard techniques: 1. Initial algebra
+construction 2. Limit of finite approximations 3. Category-theoretic
+solution in CPO
-### 4.2 Fixed Points for Recursion
+==== 4.2 Fixed Points for Recursion
For recursive functions, we use the least fixed point:
-```
+....
ℱ⟦to f(x) { ...f(e)... }⟧ = fix(λφ. λv. λC.
let ρ = [x ↦ v, f ↦ φ] in
𝒮*⟦body⟧ρ C (λv. v))
-```
+....
-Where `fix` is the least fixed point operator on continuous functions.
+Where `+fix+` is the least fixed point operator on continuous functions.
----
+'''''
-## 5. Algebraic Laws
+=== 5. Algebraic Laws
-### 5.1 Expression Equivalences
+==== 5.1 Expression Equivalences
-```
+....
-- Commutativity
e₁ + e₂ ≡ e₂ + e₁ (for numeric e₁, e₂)
e₁ * e₂ ≡ e₂ * e₁ (for numeric e₁, e₂)
@@ -494,11 +495,11 @@ e₁ * (e₂ + e₃) ≡ (e₁ * e₂) + (e₁ * e₃)
unwrap(Okay(e)) ≡ e
isOkay(Okay(e)) ≡ true
isOkay(Oops(e)) ≡ false
-```
+....
-### 5.2 Statement Equivalences
+==== 5.2 Statement Equivalences
-```
+....
-- Idempotent assignment
x = e; x = e ≡ x = e
@@ -513,46 +514,50 @@ only if okay p { s } ≡ skip (when p is denied)
repeat 0 times { s } ≡ skip
repeat 1 times { s } ≡ s
repeat (n+1) times { s } ≡ s; repeat n times { s }
-```
+....
----
+'''''
-## 6. Extensions
+=== 6. Extensions
-### 6.1 Dimensional Analysis (Future Work)
+==== 6.1 Dimensional Analysis (Future Work)
-**TODO:** Extend value domain with units:
+*TODO:* Extend value domain with units:
-```
+....
𝕍ᵤ = (ℤ₆₄ × Unit) + (ℝ₆₄ × Unit) + ...
Unit = m^α · kg^β · s^γ · A^δ · K^ε · mol^ζ · cd^η
where α,β,γ,δ,ε,ζ,η ∈ ℤ
-```
+....
Semantic rules would then include unit checking:
-```
+....
ℰ⟦e₁ + e₂⟧ρ C =
let (v₁, u₁) = ℰ⟦e₁⟧ρ C in
let (v₂, u₂) = ℰ⟦e₂⟧ρ C in
if u₁ = u₂ then (v₁ + v₂, u₁) else ⊥
-```
+....
-### 6.2 Effect Semantics (Future Work)
+==== 6.2 Effect Semantics (Future Work)
-**TODO:** Model side effects using monads or algebraic effects:
+*TODO:* Model side effects using monads or algebraic effects:
-```
+....
𝕍ₑ = T(𝕍)
where T = State × IO × Consent × Error
-```
+....
----
+'''''
-## References
+=== References
-1. Scott, D.S. (1970). "Outline of a Mathematical Theory of Computation"
-2. Stoy, J.E. (1977). "Denotational Semantics: The Scott-Strachey Approach"
-3. Winskel, G. (1993). "The Formal Semantics of Programming Languages"
-4. Schmidt, D.A. (1986). "Denotational Semantics: A Methodology for Language Development"
+[arabic]
+. Scott, D.S. (1970). "`Outline of a Mathematical Theory of
+Computation`"
+. Stoy, J.E. (1977). "`Denotational Semantics: The Scott-Strachey
+Approach`"
+. Winskel, G. (1993). "`The Formal Semantics of Programming Languages`"
+. Schmidt, D.A. (1986). "`Denotational Semantics: A Methodology for
+Language Development`"
diff --git a/docs/proofs/formal-semantics/grammar-proofs.adoc b/docs/proofs/formal-semantics/grammar-proofs.adoc
new file mode 100644
index 0000000..726c2b5
--- /dev/null
+++ b/docs/proofs/formal-semantics/grammar-proofs.adoc
@@ -0,0 +1,493 @@
+== WokeLang Grammar and Parsing Proofs
+
+This document provides formal proofs about the WokeLang grammar,
+including unambiguity, decidability, and parser correctness.
+
+____
+*Machine-checked status.* The prose below is being mechanized. The
+precedence/associativity/completeness/unambiguity/termination claims for
+the expression core are now *machine-checked* in
+link:../verification/WokeGrammar.lean[`+../verification/WokeGrammar.lean+`]
+(Lean 4.30.0, CI-gated, `+sorry+`-free, axiom-clean). See
+link:../verification/GRAMMAR-PROOF-INVENTORY.md[`+../verification/GRAMMAR-PROOF-INVENTORY.md+`]
+for the full claim-by-claim map of what is proven, what is concretely
+witnessed, and what is honestly flagged as out of reach.
+____
+
+=== 1. Grammar Classification
+
+==== 1.1 Grammar Hierarchy
+
+The WokeLang grammar belongs to the following classes:
+
+[cols=",,",options="header",]
+|===
+|Class |Membership |Justification
+|Context-Free (CFG) |✓ |All productions are context-free
+|LL(1) |✗ |Requires limited lookahead disambiguation
+|LL(k) |✓ |k ≤ 2 for all constructs
+|LR(1) |✓ |Deterministic bottom-up parsing possible
+|LALR(1) |✓ |Parser generator compatible
+|===
+
+==== 1.2 Formal Grammar Definition
+
+The grammar G = (V, Σ, R, S) where:
+
+* *V*: \{program, top_item, function_def, statement, expression, …}
+* *Σ*: \{to, remember, when, otherwise, +, -, *, …}
+* *R*: Production rules (see grammar.ebnf)
+* *S*: program (start symbol)
+
+'''''
+
+=== 2. Grammar Properties
+
+==== 2.1 No Left Recursion
+
+*Theorem 2.1:* The WokeLang grammar contains no left recursion.
+
+*Proof:* By inspection of all productions:
+
+[cols=",,",options="header",]
+|===
+|Non-terminal |First symbols |Left-recursive?
+|program |to, worker, thanks, … |No
+|function_def |to |No
+|statement |remember, when, … |No
+|expression |literal, identifier, ( |No
+|logical_or |logical_and |No (right-recursive)
+|===
+
+Expression precedence uses right-recursion:
+
+....
+expression = logical_or
+logical_or = logical_and { "or" logical_and }
+....
+
+The `+{ }+` repetition prevents left-recursion. □
+
+____
+*Correction (machine-checked, `+WokeGrammarStructure.lean/.v+`).* This
+blanket claim is *inaccurate for the grammar as literally written*: the
+`+pattern+` production has the guard alternative
+`+pattern = … | pattern "when" expression+`, which is _directly
+left-recursive_ (`+guard_pattern_is_left_recursive+`). No left recursion
+holds for the *implemented* grammar (the parser does not implement the
+guard alternative — see the grammar’s own NOTE), which is what
+`+no_left_recursion+` proves. The table above also omits `+pattern+`;
+with the guard alternative it is the sole left-recursive production.
+____
+
+==== 2.2 No Ambiguity
+
+*Theorem 2.2:* The WokeLang grammar is unambiguous.
+
+*Proof approach:* Show that every valid input has exactly one parse
+tree.
+
+*Disambiguation mechanisms:*
+
+[arabic]
+. *Operator Precedence:* Explicit precedence levels (1-8)
+. *Associativity:* All binary operators are left-associative
+. *Keyword Priority:* Reserved keywords cannot be identifiers
+. *Longest Match:* Lexer uses maximal munch
+
+*Critical cases:*
+
+*Case: Dangling else*
+
+....
+when x { when y { A } otherwise { B } }
+....
+
+The `+otherwise+` binds to the nearest `+when+`:
+
+....
+when x { (when y { A } otherwise { B }) }
+....
+
+*Rule:* `+otherwise+` is optional and binds to innermost `+when+`.
+
+*Case: Operator chains*
+
+....
+1 + 2 * 3 - 4
+....
+
+Parses as:
+
+....
+((1 + (2 * 3)) - 4)
+....
+
+*Rule:* Higher precedence binds tighter; left-to-right within level.
+
+*Case: Function call vs. grouping*
+
+....
+f(x)(y)
+....
+
+Parses as:
+
+....
+((f(x))(y)) -- Two function calls
+....
+
+Not ambiguous: postfix `+()+` associates left.
+
+□
+
+==== 2.3 LL(k) Property
+
+*Theorem 2.3:* WokeLang is LL(2).
+
+*Proof:* Show that 2 tokens of lookahead suffice for all parse
+decisions.
+
+*Table of First/Follow sets for critical decisions:*
+
+[width="100%",cols="34%,18%,21%,27%",options="header",]
+|===
+|Production |FIRST |FIRST₂ |Decision
+|statement → var_decl |remember |identifier |Unique
+|statement → assignment |identifier |= |Unique
+|statement → return_stmt |give |back |Unique
+|statement → conditional |when |expression |Unique
+|expression → call vs identifier |identifier |( vs other |Need 2 tokens
+|===
+
+The only ambiguity requiring 2-token lookahead is: - `+identifier+`
+(variable) vs `+identifier(+` (function call)
+
+With 2 tokens, all decisions are deterministic. □
+
+'''''
+
+=== 3. Parser Correctness
+
+==== 3.1 Soundness
+
+*Theorem 3.1 (Parser Soundness):* If `+parse(tokens) = Ok(ast)+`, then
+ast is a valid WokeLang program according to the grammar.
+
+*Proof:* By construction of the recursive descent parser.
+
+Each parsing function: - Consumes tokens matching its production -
+Recursively calls parsers for sub-productions - Returns AST nodes
+matching the grammar structure
+
+*Invariant:* At any point, the remaining token stream is a valid suffix
+of the input.
+
+*Base case:* Empty program is valid (program = \{ top_item }).
+
+*Inductive case:* Each parse function preserves the invariant and
+constructs valid AST nodes. □
+
+==== 3.2 Completeness
+
+*Theorem 3.2 (Parser Completeness):* If tokens form a valid program
+according to the grammar, then `+parse(tokens) = Ok(ast)+`.
+
+*Proof:* By induction on the derivation of the program.
+
+The parser handles all grammar productions: - All top-level items
+(function_def, worker_def, etc.) - All statement types - All expression
+forms - All operators at all precedence levels
+
+Since the grammar is unambiguous and the parser follows the grammar
+exactly, all valid inputs are accepted. □
+
+==== 3.3 Termination
+
+*Theorem 3.3 (Parser Termination):* `+parse(tokens)+` terminates for all
+inputs.
+
+*Proof:* 1. The token stream is finite 2. Each parse step consumes at
+least one token (no ε-productions in loops) 3. Recursive calls are on
+strictly smaller substrings 4. By well-founded induction on input
+length, parsing terminates □
+
+'''''
+
+=== 4. Lexical Analysis
+
+==== 4.1 Token Specification
+
+The lexer is specified by regular expressions:
+
+....
+IDENTIFIER = [a-zA-Z_][a-zA-Z0-9_]*
+INTEGER = [0-9]+
+FLOAT = [0-9]+\.[0-9]+
+STRING = "([^"\\]|\\.)*"
+OPERATOR = [+\-*/%<>=!]+
+KEYWORD = "to" | "remember" | "when" | ...
+....
+
+==== 4.2 Maximal Munch
+
+*Theorem 4.1:* The lexer uses maximal munch (longest match).
+
+*Proof:* The logos crate generates a DFA that: 1. Continues matching
+while valid transitions exist 2. Returns the longest match when stuck 3.
+Backtracks if needed (for IDENTIFIER vs KEYWORD)
+
+Example: - "`remember`" matches KEYWORD (not IDENTIFIER prefix) -
+"`remembering`" matches IDENTIFIER (not KEYWORD)
+
+==== 4.3 Keyword Priority
+
+*Theorem 4.2:* Keywords take precedence over identifiers.
+
+*Proof:* The Token enum lists keywords explicitly:
+
+[source,rust]
+----
+#[token("remember")]
+Remember,
+----
+
+The logos macro matches keywords before the generic identifier pattern.
+□
+
+'''''
+
+=== 5. Error Recovery
+
+==== 5.1 Current Implementation
+
+The current parser does not implement error recovery: - First error
+terminates parsing - Error location (span) is reported - No panic mode
+or phrase-level recovery
+
+==== 5.2 TODO: Error Recovery Strategies
+
+*Panic Mode:*
+
+....
+fn sync_to_statement(&mut self) {
+ while !self.at_end() && !self.check_statement_start() {
+ self.advance();
+ }
+}
+....
+
+*Phrase-Level Recovery:*
+
+....
+fn recover_from_error(&mut self, expected: TokenKind) {
+ if self.check(expected) {
+ self.advance();
+ } else {
+ self.report_error();
+ self.skip_to_sync_point();
+ }
+}
+....
+
+'''''
+
+=== 6. Pratt Parsing for Expressions
+
+==== 6.1 Algorithm
+
+The expression parser uses Pratt parsing (top-down operator precedence):
+
+[source,rust]
+----
+fn parse_expression_bp(&mut self, min_bp: u8) -> Result {
+ let mut lhs = self.parse_prefix()?;
+
+ loop {
+ let op = self.peek_operator();
+ let (l_bp, r_bp) = self.infix_binding_power(op);
+
+ if l_bp < min_bp {
+ break;
+ }
+
+ self.advance();
+ let rhs = self.parse_expression_bp(r_bp)?;
+ lhs = Expr::Binary(op, lhs, rhs);
+ }
+
+ Ok(lhs)
+}
+----
+
+==== 6.2 Correctness
+
+*Theorem 6.1:* Pratt parsing produces correct precedence.
+
+*Proof:* By induction on expression structure.
+
+*Base case:* Atoms (literals, identifiers) have no subexpressions.
+
+*Inductive case:* For `+e₁ op₁ e₂ op₂ e₃+`: - If prec(op₁) ≥ prec(op₂):
+parse as `+(e₁ op₁ e₂) op₂ e₃+` - If prec(op₁) < prec(op₂): parse as
+`+e₁ op₁ (e₂ op₂ e₃)+`
+
+The binding power comparison ensures this: - `+l_bp < min_bp+` causes
+break, grouping left - Otherwise, recursive call with `+r_bp+` parses
+right subexpression
+
+□
+
+==== 6.3 Associativity
+
+*Left associativity:* `+l_bp < r_bp+` for the same operator -
+`+a + b + c+` parses as `+(a + b) + c+`
+
+*Right associativity:* `+l_bp > r_bp+` (not used in WokeLang) - Would
+parse `+a ^ b ^ c+` as `+a ^ (b ^ c)+`
+
+'''''
+
+=== 7. Formal Language Theory
+
+____
+*Mechanization status.* §7.1 *not-regular is now machine-checked* in
+link:../verification/WokeGrammarRegular.lean[`+../verification/WokeGrammarRegular.lean+`]:
+a from-scratch finite pigeonhole + a `+Fin k+` DFA + the fooling-set
+argument on `+aⁿbⁿ+` (≅ the grammar’s balanced nesting `+(ⁿ x )ⁿ+`),
+Mathlib-free and `+sorry+`-free. §7.3 *CFL closure under ∪, ·, ** is now
+machine-checked too, in
+link:../verification/WokeGrammarCFL.lean[`+../verification/WokeGrammarCFL.lean+`]
+(a CFG derivation relation + union/concat/star grammar constructions,
+Mathlib-free, `+sorry+`-free). The *pumping lemma for context-free
+languages* — which even Mathlib lacks — is now machine-checked from
+scratch in core Lean in
+link:../verification/WokeGrammarPumping.lean[`+../verification/WokeGrammarPumping.lean+`]
+(`+cfl_pumping+`: parse-tree spine navigation + finite pigeonhole ⇒ the
+`+uvwxy+` decomposition with `+1 ≤ |vx|+` and `+|vwx| ≤ 2^(card+1)+`).
+As its canonical application, the same file machine-checks
+*`+aⁿbⁿcⁿ ∉ CFL+`* (`+anbncn_not_cfl+`) — the standard witness that the
+CFLs are not closed under ∩ / ¬ (pump down to `+i = 0+` ⇒ equal
+letter-counts ⇒ the window spans `+a+`…`+c+` ⇒ `+|vwx| > p+`). The full
+§7.3 *non-closure under ∩* is then machine-checked too
+(`+cfl_not_closed_inter+`): the witnesses `+L₁ = {aⁱbⁱcʲ}+` and
+`+L₂ = {aᵐbⁿcⁿ}+` are each proved context-free by an explicit ε-free
+binary-normal-form grammar (with soundness + completeness), and
+`+L₁ ∩ L₂ = {aⁿbⁿcⁿ}+` is not. Status in
+`+../verification/GRAMMAR-PROOF-INVENTORY.md+`.
+____
+
+==== 7.1 Chomsky Hierarchy Position
+
+....
+Regular ⊂ Context-Free ⊂ Context-Sensitive ⊂ Recursively Enumerable
+ ↑ ↑
+Tokens WokeLang
+....
+
+==== 7.2 Pumping Lemma Application
+
+*Theorem 7.1:* WokeLang is not regular.
+
+*Proof:* Consider balanced parentheses in expressions: `+(((...)))+`.
+
+Assume WokeLang is regular. By pumping lemma: - For pumping length p,
+consider `+(^p )^p+` (p open, p close parens) - Pumping the first part
+gives `+(^(p+k) )^p+` for some k > 0 - This is not balanced, so not in
+WokeLang
+
+Contradiction. WokeLang is not regular. □
+
+==== 7.3 CFL Closure Properties
+
+WokeLang, as a CFL, is closed under: - Union (combining dialects) -
+Concatenation (sequencing programs) - Kleene star (repetition)
+
+Not closed under: - Intersection (combining constraints) - Complement
+(defining forbidden programs)
+
+'''''
+
+=== 8. EBNF to BNF Conversion
+
+==== 8.1 Repetition
+
+EBNF: `+{ statement }+` BNF:
+
+....
+statement_list ::= ε | statement statement_list
+....
+
+==== 8.2 Option
+
+EBNF: `+[ return_type ]+` BNF:
+
+....
+opt_return_type ::= ε | return_type
+....
+
+==== 8.3 Grouping
+
+EBNF: `+( "+" | "-" )+` BNF:
+
+....
+add_op ::= "+" | "-"
+....
+
+'''''
+
+=== 9. Grammar Metrics
+
+==== 9.1 Size
+
+[cols=",",options="header",]
+|===
+|Metric |Value
+|Non-terminals |45
+|Terminals |78
+|Productions |89
+|Total symbols |~250
+|===
+
+==== 9.2 Complexity
+
+[cols=",",options="header",]
+|===
+|Metric |Value
+|Maximum RHS length |12 (function_def)
+|Maximum nesting |5
+|Cyclic dependencies |2 (expression ↔ statement)
+|===
+
+'''''
+
+=== 10. Verified Parsing (Future Work)
+
+==== 10.1 Parser Combinators in Coq/Lean
+
+[source,coq]
+----
+Inductive parser (A : Type) : Type :=
+ | Pure : A -> parser A
+ | Bind : forall B, parser B -> (B -> parser A) -> parser A
+ | Char : (char -> bool) -> parser char
+ | Fail : parser A.
+----
+
+==== 10.2 Total Parser Guarantee
+
+A verified parser would prove: 1. *Totality:* Parser terminates on all
+inputs 2. *Correctness:* Accepted inputs match grammar 3.
+*Completeness:* All grammar strings are accepted
+
+'''''
+
+=== References
+
+[arabic]
+. Aho, A.V. et al. (2006). "`Compilers: Principles, Techniques, and
+Tools`"
+. Pratt, V.R. (1973). "`Top Down Operator Precedence`"
+. Ford, B. (2004). "`Parsing Expression Grammars`"
+. Firsov, D. and Uustalu, T. (2014). "`Certified CYK Parsing of
+Context-Free Languages`"
diff --git a/docs/proofs/formal-semantics/grammar-proofs.md b/docs/proofs/formal-semantics/grammar-proofs.md
deleted file mode 100644
index b6e2e51..0000000
--- a/docs/proofs/formal-semantics/grammar-proofs.md
+++ /dev/null
@@ -1,454 +0,0 @@
-
-# WokeLang Grammar and Parsing Proofs
-
-This document provides formal proofs about the WokeLang grammar, including unambiguity, decidability, and parser correctness.
-
-> **Machine-checked status.** The prose below is being mechanized. The
-> precedence/associativity/completeness/unambiguity/termination claims for the
-> expression core are now **machine-checked** in
-> [`../verification/WokeGrammar.lean`](../verification/WokeGrammar.lean)
-> (Lean 4.30.0, CI-gated, `sorry`-free, axiom-clean). See
-> [`../verification/GRAMMAR-PROOF-INVENTORY.md`](../verification/GRAMMAR-PROOF-INVENTORY.md)
-> for the full claim-by-claim map of what is proven, what is concretely
-> witnessed, and what is honestly flagged as out of reach.
-
-## 1. Grammar Classification
-
-### 1.1 Grammar Hierarchy
-
-The WokeLang grammar belongs to the following classes:
-
-| Class | Membership | Justification |
-|-------|------------|---------------|
-| Context-Free (CFG) | ✓ | All productions are context-free |
-| LL(1) | ✗ | Requires limited lookahead disambiguation |
-| LL(k) | ✓ | k ≤ 2 for all constructs |
-| LR(1) | ✓ | Deterministic bottom-up parsing possible |
-| LALR(1) | ✓ | Parser generator compatible |
-
-### 1.2 Formal Grammar Definition
-
-The grammar G = (V, Σ, R, S) where:
-
-- **V**: {program, top_item, function_def, statement, expression, ...}
-- **Σ**: {to, remember, when, otherwise, +, -, *, ...}
-- **R**: Production rules (see grammar.ebnf)
-- **S**: program (start symbol)
-
----
-
-## 2. Grammar Properties
-
-### 2.1 No Left Recursion
-
-**Theorem 2.1:** The WokeLang grammar contains no left recursion.
-
-**Proof:** By inspection of all productions:
-
-| Non-terminal | First symbols | Left-recursive? |
-|--------------|---------------|-----------------|
-| program | to, worker, thanks, ... | No |
-| function_def | to | No |
-| statement | remember, when, ... | No |
-| expression | literal, identifier, ( | No |
-| logical_or | logical_and | No (right-recursive) |
-
-Expression precedence uses right-recursion:
-```
-expression = logical_or
-logical_or = logical_and { "or" logical_and }
-```
-
-The `{ }` repetition prevents left-recursion. □
-
-> **Correction (machine-checked, `WokeGrammarStructure.lean/.v`).** This blanket
-> claim is **inaccurate for the grammar as literally written**: the `pattern`
-> production has the guard alternative `pattern = … | pattern "when" expression`,
-> which is *directly left-recursive* (`guard_pattern_is_left_recursive`). No
-> left recursion holds for the **implemented** grammar (the parser does not
-> implement the guard alternative — see the grammar's own NOTE), which is what
-> `no_left_recursion` proves. The table above also omits `pattern`; with the
-> guard alternative it is the sole left-recursive production.
-
-### 2.2 No Ambiguity
-
-**Theorem 2.2:** The WokeLang grammar is unambiguous.
-
-**Proof approach:** Show that every valid input has exactly one parse tree.
-
-**Disambiguation mechanisms:**
-
-1. **Operator Precedence:** Explicit precedence levels (1-8)
-2. **Associativity:** All binary operators are left-associative
-3. **Keyword Priority:** Reserved keywords cannot be identifiers
-4. **Longest Match:** Lexer uses maximal munch
-
-**Critical cases:**
-
-**Case: Dangling else**
-```
-when x { when y { A } otherwise { B } }
-```
-The `otherwise` binds to the nearest `when`:
-```
-when x { (when y { A } otherwise { B }) }
-```
-**Rule:** `otherwise` is optional and binds to innermost `when`.
-
-**Case: Operator chains**
-```
-1 + 2 * 3 - 4
-```
-Parses as:
-```
-((1 + (2 * 3)) - 4)
-```
-**Rule:** Higher precedence binds tighter; left-to-right within level.
-
-**Case: Function call vs. grouping**
-```
-f(x)(y)
-```
-Parses as:
-```
-((f(x))(y)) -- Two function calls
-```
-Not ambiguous: postfix `()` associates left.
-
-□
-
-### 2.3 LL(k) Property
-
-**Theorem 2.3:** WokeLang is LL(2).
-
-**Proof:** Show that 2 tokens of lookahead suffice for all parse decisions.
-
-**Table of First/Follow sets for critical decisions:**
-
-| Production | FIRST | FIRST₂ | Decision |
-|------------|-------|--------|----------|
-| statement → var_decl | remember | identifier | Unique |
-| statement → assignment | identifier | = | Unique |
-| statement → return_stmt | give | back | Unique |
-| statement → conditional | when | expression | Unique |
-| expression → call vs identifier | identifier | ( vs other | Need 2 tokens |
-
-The only ambiguity requiring 2-token lookahead is:
-- `identifier` (variable) vs `identifier(` (function call)
-
-With 2 tokens, all decisions are deterministic. □
-
----
-
-## 3. Parser Correctness
-
-### 3.1 Soundness
-
-**Theorem 3.1 (Parser Soundness):** If `parse(tokens) = Ok(ast)`, then ast is a valid WokeLang program according to the grammar.
-
-**Proof:** By construction of the recursive descent parser.
-
-Each parsing function:
-- Consumes tokens matching its production
-- Recursively calls parsers for sub-productions
-- Returns AST nodes matching the grammar structure
-
-**Invariant:** At any point, the remaining token stream is a valid suffix of the input.
-
-**Base case:** Empty program is valid (program = { top_item }).
-
-**Inductive case:** Each parse function preserves the invariant and constructs valid AST nodes. □
-
-### 3.2 Completeness
-
-**Theorem 3.2 (Parser Completeness):** If tokens form a valid program according to the grammar, then `parse(tokens) = Ok(ast)`.
-
-**Proof:** By induction on the derivation of the program.
-
-The parser handles all grammar productions:
-- All top-level items (function_def, worker_def, etc.)
-- All statement types
-- All expression forms
-- All operators at all precedence levels
-
-Since the grammar is unambiguous and the parser follows the grammar exactly, all valid inputs are accepted. □
-
-### 3.3 Termination
-
-**Theorem 3.3 (Parser Termination):** `parse(tokens)` terminates for all inputs.
-
-**Proof:**
-1. The token stream is finite
-2. Each parse step consumes at least one token (no ε-productions in loops)
-3. Recursive calls are on strictly smaller substrings
-4. By well-founded induction on input length, parsing terminates □
-
----
-
-## 4. Lexical Analysis
-
-### 4.1 Token Specification
-
-The lexer is specified by regular expressions:
-
-```
-IDENTIFIER = [a-zA-Z_][a-zA-Z0-9_]*
-INTEGER = [0-9]+
-FLOAT = [0-9]+\.[0-9]+
-STRING = "([^"\\]|\\.)*"
-OPERATOR = [+\-*/%<>=!]+
-KEYWORD = "to" | "remember" | "when" | ...
-```
-
-### 4.2 Maximal Munch
-
-**Theorem 4.1:** The lexer uses maximal munch (longest match).
-
-**Proof:** The logos crate generates a DFA that:
-1. Continues matching while valid transitions exist
-2. Returns the longest match when stuck
-3. Backtracks if needed (for IDENTIFIER vs KEYWORD)
-
-Example:
-- "remember" matches KEYWORD (not IDENTIFIER prefix)
-- "remembering" matches IDENTIFIER (not KEYWORD)
-
-### 4.3 Keyword Priority
-
-**Theorem 4.2:** Keywords take precedence over identifiers.
-
-**Proof:** The Token enum lists keywords explicitly:
-```rust
-#[token("remember")]
-Remember,
-```
-
-The logos macro matches keywords before the generic identifier pattern. □
-
----
-
-## 5. Error Recovery
-
-### 5.1 Current Implementation
-
-The current parser does not implement error recovery:
-- First error terminates parsing
-- Error location (span) is reported
-- No panic mode or phrase-level recovery
-
-### 5.2 TODO: Error Recovery Strategies
-
-**Panic Mode:**
-```
-fn sync_to_statement(&mut self) {
- while !self.at_end() && !self.check_statement_start() {
- self.advance();
- }
-}
-```
-
-**Phrase-Level Recovery:**
-```
-fn recover_from_error(&mut self, expected: TokenKind) {
- if self.check(expected) {
- self.advance();
- } else {
- self.report_error();
- self.skip_to_sync_point();
- }
-}
-```
-
----
-
-## 6. Pratt Parsing for Expressions
-
-### 6.1 Algorithm
-
-The expression parser uses Pratt parsing (top-down operator precedence):
-
-```rust
-fn parse_expression_bp(&mut self, min_bp: u8) -> Result {
- let mut lhs = self.parse_prefix()?;
-
- loop {
- let op = self.peek_operator();
- let (l_bp, r_bp) = self.infix_binding_power(op);
-
- if l_bp < min_bp {
- break;
- }
-
- self.advance();
- let rhs = self.parse_expression_bp(r_bp)?;
- lhs = Expr::Binary(op, lhs, rhs);
- }
-
- Ok(lhs)
-}
-```
-
-### 6.2 Correctness
-
-**Theorem 6.1:** Pratt parsing produces correct precedence.
-
-**Proof:** By induction on expression structure.
-
-**Base case:** Atoms (literals, identifiers) have no subexpressions.
-
-**Inductive case:** For `e₁ op₁ e₂ op₂ e₃`:
-- If prec(op₁) ≥ prec(op₂): parse as `(e₁ op₁ e₂) op₂ e₃`
-- If prec(op₁) < prec(op₂): parse as `e₁ op₁ (e₂ op₂ e₃)`
-
-The binding power comparison ensures this:
-- `l_bp < min_bp` causes break, grouping left
-- Otherwise, recursive call with `r_bp` parses right subexpression
-
-□
-
-### 6.3 Associativity
-
-**Left associativity:** `l_bp < r_bp` for the same operator
-- `a + b + c` parses as `(a + b) + c`
-
-**Right associativity:** `l_bp > r_bp` (not used in WokeLang)
-- Would parse `a ^ b ^ c` as `a ^ (b ^ c)`
-
----
-
-## 7. Formal Language Theory
-
-> **Mechanization status.** §7.1 **not-regular is now machine-checked** in
-> [`../verification/WokeGrammarRegular.lean`](../verification/WokeGrammarRegular.lean):
-> a from-scratch finite pigeonhole + a `Fin k` DFA + the fooling-set argument on
-> `aⁿbⁿ` (≅ the grammar's balanced nesting `(ⁿ x )ⁿ`), Mathlib-free and `sorry`-free.
-> §7.3 **CFL closure under ∪, ·, \*** is now machine-checked too, in
-> [`../verification/WokeGrammarCFL.lean`](../verification/WokeGrammarCFL.lean)
-> (a CFG derivation relation + union/concat/star grammar constructions,
-> Mathlib-free, `sorry`-free). The **pumping lemma for context-free languages**
-> — which even Mathlib lacks — is now machine-checked from scratch in core Lean in
-> [`../verification/WokeGrammarPumping.lean`](../verification/WokeGrammarPumping.lean)
-> (`cfl_pumping`: parse-tree spine navigation + finite pigeonhole ⇒ the `uvwxy`
-> decomposition with `1 ≤ |vx|` and `|vwx| ≤ 2^(card+1)`). As its canonical
-> application, the same file machine-checks **`aⁿbⁿcⁿ ∉ CFL`** (`anbncn_not_cfl`) —
-> the standard witness that the CFLs are not closed under ∩ / ¬ (pump down to
-> `i = 0` ⇒ equal letter-counts ⇒ the window spans `a`…`c` ⇒ `|vwx| > p`). The
-> full §7.3 **non-closure under ∩** is then machine-checked too
-> (`cfl_not_closed_inter`): the witnesses `L₁ = {aⁱbⁱcʲ}` and `L₂ = {aᵐbⁿcⁿ}` are
-> each proved context-free by an explicit ε-free binary-normal-form grammar (with
-> soundness + completeness), and `L₁ ∩ L₂ = {aⁿbⁿcⁿ}` is not. Status in
-> `../verification/GRAMMAR-PROOF-INVENTORY.md`.
-
-### 7.1 Chomsky Hierarchy Position
-
-```
-Regular ⊂ Context-Free ⊂ Context-Sensitive ⊂ Recursively Enumerable
- ↑ ↑
-Tokens WokeLang
-```
-
-### 7.2 Pumping Lemma Application
-
-**Theorem 7.1:** WokeLang is not regular.
-
-**Proof:** Consider balanced parentheses in expressions: `(((...)))`.
-
-Assume WokeLang is regular. By pumping lemma:
-- For pumping length p, consider `(^p )^p` (p open, p close parens)
-- Pumping the first part gives `(^(p+k) )^p` for some k > 0
-- This is not balanced, so not in WokeLang
-
-Contradiction. WokeLang is not regular. □
-
-### 7.3 CFL Closure Properties
-
-WokeLang, as a CFL, is closed under:
-- Union (combining dialects)
-- Concatenation (sequencing programs)
-- Kleene star (repetition)
-
-Not closed under:
-- Intersection (combining constraints)
-- Complement (defining forbidden programs)
-
----
-
-## 8. EBNF to BNF Conversion
-
-### 8.1 Repetition
-
-EBNF: `{ statement }`
-BNF:
-```
-statement_list ::= ε | statement statement_list
-```
-
-### 8.2 Option
-
-EBNF: `[ return_type ]`
-BNF:
-```
-opt_return_type ::= ε | return_type
-```
-
-### 8.3 Grouping
-
-EBNF: `( "+" | "-" )`
-BNF:
-```
-add_op ::= "+" | "-"
-```
-
----
-
-## 9. Grammar Metrics
-
-### 9.1 Size
-
-| Metric | Value |
-|--------|-------|
-| Non-terminals | 45 |
-| Terminals | 78 |
-| Productions | 89 |
-| Total symbols | ~250 |
-
-### 9.2 Complexity
-
-| Metric | Value |
-|--------|-------|
-| Maximum RHS length | 12 (function_def) |
-| Maximum nesting | 5 |
-| Cyclic dependencies | 2 (expression ↔ statement) |
-
----
-
-## 10. Verified Parsing (Future Work)
-
-### 10.1 Parser Combinators in Coq/Lean
-
-```coq
-Inductive parser (A : Type) : Type :=
- | Pure : A -> parser A
- | Bind : forall B, parser B -> (B -> parser A) -> parser A
- | Char : (char -> bool) -> parser char
- | Fail : parser A.
-```
-
-### 10.2 Total Parser Guarantee
-
-A verified parser would prove:
-1. **Totality:** Parser terminates on all inputs
-2. **Correctness:** Accepted inputs match grammar
-3. **Completeness:** All grammar strings are accepted
-
----
-
-## References
-
-1. Aho, A.V. et al. (2006). "Compilers: Principles, Techniques, and Tools"
-2. Pratt, V.R. (1973). "Top Down Operator Precedence"
-3. Ford, B. (2004). "Parsing Expression Grammars"
-4. Firsov, D. and Uustalu, T. (2014). "Certified CYK Parsing of Context-Free Languages"
diff --git a/docs/proofs/formal-semantics/operational-semantics.md b/docs/proofs/formal-semantics/operational-semantics.adoc
similarity index 66%
rename from docs/proofs/formal-semantics/operational-semantics.md
rename to docs/proofs/formal-semantics/operational-semantics.adoc
index 72b0472..fe58b2d 100644
--- a/docs/proofs/formal-semantics/operational-semantics.md
+++ b/docs/proofs/formal-semantics/operational-semantics.adoc
@@ -1,16 +1,14 @@
-
-# WokeLang Operational Semantics
+== WokeLang Operational Semantics
-This document provides a complete formal specification of WokeLang's operational semantics using both big-step (natural) and small-step (structural operational) semantics.
+This document provides a complete formal specification of WokeLang’s
+operational semantics using both big-step (natural) and small-step
+(structural operational) semantics.
-## 1. Abstract Syntax
+=== 1. Abstract Syntax
-### 1.1 Syntactic Categories
+==== 1.1 Syntactic Categories
-```
+....
v ∈ Value ::= n | f | s | b | unit | [v₁,...,vₙ] | Okay(v) | Oops(s)
e ∈ Expr ::= v | x | e₁ op e₂ | uop e | f(e₁,...,eₙ) | e[e] | e measured in u
s ∈ Stmt ::= remember x = e | x = e | give back e | when e {s*} otherwise {s*}
@@ -20,77 +18,77 @@ s ∈ Stmt ::= remember x = e | x = e | give back e | when e {s*} otherw
p ∈ Program ::= item*
item ∈ TopLevel ::= to f(params) → τ {s*} | worker x {s*} | thanks to {entries}
| only if okay s {s*} | #pragma on/off
-```
+....
-### 1.2 Values
+==== 1.2 Values
-```
+....
n ∈ ℤ (64-bit signed integers)
f ∈ ℝ (64-bit floating point)
s ∈ String (UTF-8 strings)
b ∈ {true, false} (booleans)
unit (unit value)
-```
+....
-### 1.3 Binary Operators
+==== 1.3 Binary Operators
-```
+....
op ∈ BinOp ::= + | - | * | / | % | == | != | < | > | <= | >= | and | or
-```
+....
-### 1.4 Unary Operators
+==== 1.4 Unary Operators
-```
+....
uop ∈ UnOp ::= - | not
-```
+....
----
+'''''
-## 2. Semantic Domains
+=== 2. Semantic Domains
-### 2.1 Environment
+==== 2.1 Environment
-An environment `ρ` maps identifiers to values:
+An environment `+ρ+` maps identifiers to values:
-```
+....
ρ : Env = Ident → Value
-```
+....
-Environment operations:
-- `ρ[x ↦ v]` : extend environment with binding
-- `ρ(x)` : lookup value (undefined if x ∉ dom(ρ))
+Environment operations: - `+ρ[x ↦ v]+` : extend environment with binding
+- `+ρ(x)+` : lookup value (undefined if x ∉ dom(ρ))
-### 2.2 Function Store
+==== 2.2 Function Store
-A function store `Φ` maps function names to definitions:
+A function store `+Φ+` maps function names to definitions:
-```
+....
Φ : FuncStore = Ident → FunctionDef
-```
+....
-### 2.3 Consent State
+==== 2.3 Consent State
-Consent state `C` tracks granted permissions:
+Consent state `+C+` tracks granted permissions:
-```
+....
C : ConsentState = ℘(Permission)
-```
+....
-### 2.4 Configuration
+==== 2.4 Configuration
-A configuration is a tuple `⟨e, ρ, Φ, C⟩` or `⟨s, ρ, Φ, C⟩`.
+A configuration is a tuple `+⟨e, ρ, Φ, C⟩+` or `+⟨s, ρ, Φ, C⟩+`.
----
+'''''
-## 3. Big-Step Semantics (Natural Semantics)
+=== 3. Big-Step Semantics (Natural Semantics)
-We define the judgment `⟨e, ρ, Φ⟩ ⇓ v` meaning "expression e evaluates to value v in environment ρ with function store Φ".
+We define the judgment `+⟨e, ρ, Φ⟩ ⇓ v+` meaning "`expression e
+evaluates to value v in environment ρ with function store Φ`".
-### 3.1 Expression Evaluation
+==== 3.1 Expression Evaluation
-#### Literals
+===== Literals
-```
+....
─────────────────────────── [B-Int]
⟨n, ρ, Φ⟩ ⇓ n
@@ -105,79 +103,78 @@ We define the judgment `⟨e, ρ, Φ⟩ ⇓ v` meaning "expression e evaluates t
─────────────────────────── [B-Unit]
⟨unit, ρ, Φ⟩ ⇓ unit
-```
+....
-#### Variables
+===== Variables
-```
+....
x ∈ dom(ρ)
─────────────────────────── [B-Var]
⟨x, ρ, Φ⟩ ⇓ ρ(x)
-```
+....
-#### Binary Operations
+===== Binary Operations
-```
+....
⟨e₁, ρ, Φ⟩ ⇓ v₁ ⟨e₂, ρ, Φ⟩ ⇓ v₂ v = v₁ ⊕ v₂
────────────────────────────────────────────────── [B-BinOp]
⟨e₁ op e₂, ρ, Φ⟩ ⇓ v
-```
+....
-Where `⊕` is the semantic interpretation of `op`:
+Where `+⊕+` is the semantic interpretation of `+op+`:
-| op | Integer semantics | Float semantics | String semantics |
-|----|-------------------|-----------------|------------------|
-| + | n₁ + n₂ | f₁ + f₂ | s₁ ++ s₂ |
-| - | n₁ - n₂ | f₁ - f₂ | undefined |
-| * | n₁ × n₂ | f₁ × f₂ | undefined |
-| / | n₁ ÷ n₂ (n₂ ≠ 0) | f₁ / f₂ | undefined |
-| % | n₁ mod n₂ | undefined | undefined |
-| == | n₁ = n₂ | f₁ = f₂ | s₁ = s₂ |
-| < | n₁ < n₂ | f₁ < f₂ | s₁ <ₗₑₓ s₂ |
+[cols=",,,",options="header",]
+|===
+|op |Integer semantics |Float semantics |String semantics
+|+ |n₁ + n₂ |f₁ + f₂ |s₁ ++ s₂
+|- |n₁ - n₂ |f₁ - f₂ |undefined
+|* |n₁ × n₂ |f₁ × f₂ |undefined
+|/ |n₁ ÷ n₂ (n₂ ≠ 0) |f₁ / f₂ |undefined
+|% |n₁ mod n₂ |undefined |undefined
+|== |n₁ = n₂ |f₁ = f₂ |s₁ = s₂
+|< |n₁ < n₂ |f₁ < f₂ |s₁ <ₗₑₓ s₂
+|===
-#### Unary Operations
+===== Unary Operations
-```
+....
⟨e, ρ, Φ⟩ ⇓ v v' = ⊖v
─────────────────────────── [B-UnOp]
⟨uop e, ρ, Φ⟩ ⇓ v'
-```
+....
-Where:
-- `⊖(-) n = -n`
-- `⊖(-) f = -f`
-- `⊖(not) b = ¬b`
+Where: - `+⊖(-) n = -n+` - `+⊖(-) f = -f+` - `+⊖(not) b = ¬b+`
-#### Function Calls
+===== Function Calls
-```
+....
Φ(f) = to f(x₁,...,xₙ) { body }
⟨e₁, ρ, Φ⟩ ⇓ v₁ ... ⟨eₙ, ρ, Φ⟩ ⇓ vₙ
ρ' = [x₁ ↦ v₁, ..., xₙ ↦ vₙ]
⟨body, ρ', Φ⟩ ⇓ᵇ (v, ρ'')
─────────────────────────────────────── [B-Call]
⟨f(e₁,...,eₙ), ρ, Φ⟩ ⇓ v
-```
+....
-#### Arrays
+===== Arrays
-```
+....
⟨e₁, ρ, Φ⟩ ⇓ v₁ ... ⟨eₙ, ρ, Φ⟩ ⇓ vₙ
────────────────────────────────────── [B-Array]
⟨[e₁,...,eₙ], ρ, Φ⟩ ⇓ [v₁,...,vₙ]
-```
+....
-#### Array Indexing
+===== Array Indexing
-```
+....
⟨e₁, ρ, Φ⟩ ⇓ [v₀,...,vₖ] ⟨e₂, ρ, Φ⟩ ⇓ n 0 ≤ n ≤ k
───────────────────────────────────────────────────────── [B-Index]
⟨e₁[e₂], ρ, Φ⟩ ⇓ vₙ
-```
+....
-#### Result Types
+===== Result Types
-```
+....
⟨e, ρ, Φ⟩ ⇓ v
─────────────────────────── [B-Okay]
⟨Okay(e), ρ, Φ⟩ ⇓ Okay(v)
@@ -185,124 +182,124 @@ Where:
⟨e, ρ, Φ⟩ ⇓ s
─────────────────────────── [B-Oops]
⟨Oops(e), ρ, Φ⟩ ⇓ Oops(s)
-```
+....
-#### Unit Measurement (Annotation Only)
+===== Unit Measurement (Annotation Only)
-```
+....
⟨e, ρ, Φ⟩ ⇓ v
──────────────────────────────── [B-Unit-Measure]
⟨e measured in u, ρ, Φ⟩ ⇓ v
-```
+....
-### 3.2 Statement Evaluation
+==== 3.2 Statement Evaluation
-Statement evaluation uses the judgment `⟨s, ρ, Φ, C⟩ ⇓ᵇ (result, ρ', C')` where result is either:
-- `Continue` - normal completion
-- `Return(v)` - return with value v
+Statement evaluation uses the judgment
+`+⟨s, ρ, Φ, C⟩ ⇓ᵇ (result, ρ', C')+` where result is either: -
+`+Continue+` - normal completion - `+Return(v)+` - return with value v
-#### Variable Declaration
+===== Variable Declaration
-```
+....
⟨e, ρ, Φ⟩ ⇓ v
──────────────────────────────────────────────── [B-VarDecl]
⟨remember x = e, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ[x ↦ v], C)
-```
+....
-#### Assignment
+===== Assignment
-```
+....
⟨e, ρ, Φ⟩ ⇓ v x ∈ dom(ρ)
──────────────────────────────────────────── [B-Assign]
⟨x = e, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ[x ↦ v], C)
-```
+....
-#### Return
+===== Return
-```
+....
⟨e, ρ, Φ⟩ ⇓ v
───────────────────────────────────────── [B-Return]
⟨give back e, ρ, Φ, C⟩ ⇓ᵇ (Return(v), ρ, C)
-```
+....
-#### Conditional (True Branch)
+===== Conditional (True Branch)
-```
+....
⟨e, ρ, Φ⟩ ⇓ true ⟨s₁*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
────────────────────────────────────────────────────── [B-If-True]
⟨when e {s₁*} otherwise {s₂*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-```
+....
-#### Conditional (False Branch)
+===== Conditional (False Branch)
-```
+....
⟨e, ρ, Φ⟩ ⇓ false ⟨s₂*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
─────────────────────────────────────────────────────── [B-If-False]
⟨when e {s₁*} otherwise {s₂*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-```
+....
-#### Loop (Base Case)
+===== Loop (Base Case)
-```
+....
⟨e, ρ, Φ⟩ ⇓ n n ≤ 0
─────────────────────────────────────────── [B-Loop-Zero]
⟨repeat e times {s*}, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ, C)
-```
+....
-#### Loop (Inductive Case)
+===== Loop (Inductive Case)
-```
+....
⟨e, ρ, Φ⟩ ⇓ n n > 0
⟨s*, ρ, Φ, C⟩ ⇓ᵇ* (Continue, ρ', C')
⟨repeat (n-1) times {s*}, ρ', Φ, C'⟩ ⇓ᵇ (r, ρ'', C'')
───────────────────────────────────────────────────────── [B-Loop-Step]
⟨repeat e times {s*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ'', C'')
-```
+....
-#### Attempt Block (Success)
+===== Attempt Block (Success)
-```
+....
⟨s*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
──────────────────────────────────────────────────────── [B-Attempt-Ok]
⟨attempt safely {s*} or reassure msg, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-```
+....
-#### Attempt Block (Error Recovery)
+===== Attempt Block (Error Recovery)
-```
+....
⟨s*, ρ, Φ, C⟩ ⇓ᵇ* error
──────────────────────────────────────────────────────────── [B-Attempt-Err]
⟨attempt safely {s*} or reassure msg, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ, C)
-```
+....
-#### Consent Block (Granted)
+===== Consent Block (Granted)
-```
+....
perm ∈ C ⟨s*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
───────────────────────────────────────────── [B-Consent-Grant]
⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-```
+....
-#### Consent Block (Denied)
+===== Consent Block (Denied)
-```
+....
perm ∉ C
────────────────────────────────────────────── [B-Consent-Deny]
⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ, C)
-```
+....
-#### Pattern Matching
+===== Pattern Matching
-```
+....
⟨e, ρ, Φ⟩ ⇓ v
match(p₁, v) = Some(bindings) ⟨s₁*, ρ ⊕ bindings, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
─────────────────────────────────────────────────────────────────────────── [B-Match]
⟨decide based on e { p₁ → {s₁*}; ... }, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-```
+....
-Where `match(p, v)` is defined as:
+Where `+match(p, v)+` is defined as:
-```
+....
match(_, v) = Some([]) (wildcard)
match(x, v) = Some([x ↦ v]) (identifier)
match(n, n) = Some([]) (integer literal)
@@ -311,25 +308,26 @@ match(b, b) = Some([]) (boolean literal)
match(Okay(p), Okay(v)) = match(p, v) (okay pattern)
match(Oops(p), Oops(v)) = match(p, v) (oops pattern)
match(_, _) = None (no match)
-```
+....
----
+'''''
-## 4. Small-Step Semantics (Structural Operational Semantics)
+=== 4. Small-Step Semantics (Structural Operational Semantics)
-For compilation and program analysis, we also define small-step semantics using the transition relation `⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩`.
+For compilation and program analysis, we also define small-step
+semantics using the transition relation `+⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩+`.
-### 4.1 Evaluation Contexts
+==== 4.1 Evaluation Contexts
-```
+....
E ::= □ | E op e | v op E | uop E | f(v₁,...,vᵢ,E,eᵢ₊₂,...,eₙ)
| [v₁,...,vᵢ,E,eᵢ₊₂,...,eₙ] | E[e] | v[E]
| Okay(E) | Oops(E) | E measured in u
-```
+....
-### 4.2 Expression Transitions
+==== 4.2 Expression Transitions
-```
+....
⟨x, ρ, Φ⟩ → ⟨ρ(x), ρ, Φ⟩ [S-Var]
⟨v₁ op v₂, ρ, Φ⟩ → ⟨v₁ ⊕ v₂, ρ, Φ⟩ [S-BinOp]
@@ -345,13 +343,13 @@ E ::= □ | E op e | v op E | uop E | f(v₁,...,vᵢ,E,eᵢ₊₂,...,eₙ)
⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩
──────────────────────────── [S-Context]
⟨E[e], ρ, Φ⟩ → ⟨E[e'], ρ', Φ⟩
-```
+....
-### 4.3 Statement Transitions
+==== 4.3 Statement Transitions
Statement configurations include a statement list (continuation):
-```
+....
⟨remember x = v; s*, ρ, Φ, C⟩ → ⟨s*, ρ[x ↦ v], Φ, C⟩ [S-VarDecl]
⟨x = v; s*, ρ, Φ, C⟩ → ⟨s*, ρ[x ↦ v], Φ, C⟩ [S-Assign]
@@ -363,73 +361,87 @@ Statement configurations include a statement list (continuation):
⟨when false {s₁*} otherwise {s₂*}; s*, ρ, Φ, C⟩
→ ⟨s₂* ++ s*, ρ, Φ, C⟩ [S-If-False]
-```
+....
----
+'''''
-## 5. Semantic Properties
+=== 5. Semantic Properties
-### 5.1 Determinism
+==== 5.1 Determinism
-**Theorem 5.1 (Determinism):** WokeLang expression evaluation is deterministic.
+*Theorem 5.1 (Determinism):* WokeLang expression evaluation is
+deterministic.
For all expressions e, environments ρ, and function stores Φ:
-```
+....
If ⟨e, ρ, Φ⟩ ⇓ v₁ and ⟨e, ρ, Φ⟩ ⇓ v₂, then v₁ = v₂
-```
+....
-**Proof:** By structural induction on the derivation. Each inference rule has unique premises that determine the conclusion. □
+*Proof:* By structural induction on the derivation. Each inference rule
+has unique premises that determine the conclusion. □
-### 5.2 Termination
+==== 5.2 Termination
-**Theorem 5.2 (Conditional Termination):** WokeLang evaluation terminates for all programs without unbounded recursion.
+*Theorem 5.2 (Conditional Termination):* WokeLang evaluation terminates
+for all programs without unbounded recursion.
-Note: The `repeat n times` loop always terminates since n is evaluated once and decremented. Unbounded recursion can cause non-termination.
+Note: The `+repeat n times+` loop always terminates since n is evaluated
+once and decremented. Unbounded recursion can cause non-termination.
-### 5.3 Consent Safety
+==== 5.3 Consent Safety
-**Theorem 5.3 (Consent Monotonicity):** Consent state can only grow during program execution when operating in non-interactive mode.
+*Theorem 5.3 (Consent Monotonicity):* Consent state can only grow during
+program execution when operating in non-interactive mode.
-```
+....
If ⟨s, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C'), then C ⊆ C'
-```
+....
-**Proof:** By inspection of rules, only [B-Consent-Grant] can modify consent state, and it only adds permissions. □
+*Proof:* By inspection of rules, only [B-Consent-Grant] can modify
+consent state, and it only adds permissions. □
----
+'''''
-## 6. Equivalence of Semantics
+=== 6. Equivalence of Semantics
-**Theorem 6.1 (Big-Step/Small-Step Equivalence):** For any expression e:
+*Theorem 6.1 (Big-Step/Small-Step Equivalence):* For any expression e:
-```
+....
⟨e, ρ, Φ⟩ ⇓ v ⟺ ⟨e, ρ, Φ⟩ →* ⟨v, ρ, Φ⟩
-```
-
-**Proof:** Standard proof by induction on the structure of derivations, showing each big-step rule corresponds to a sequence of small-step transitions. □
-
----
-
-## 7. Reference Implementation Correspondence
-
-The operational semantics defined here corresponds directly to the tree-walking interpreter implementation in `src/interpreter/mod.rs`:
-
-| Semantic Rule | Implementation |
-|---------------|----------------|
-| B-Var | `Expr::Identifier` case in `evaluate()` |
-| B-BinOp | `apply_binary_op()` method |
-| B-Call | `call_function()` method |
-| B-VarDecl | `Statement::VarDecl` case in `execute_statement()` |
-| B-If-* | `Statement::Conditional` case |
-| B-Loop-* | `Statement::Loop` case |
-| B-Consent-* | `execute_consent_block()` method |
-| B-Match | `pattern_matches()` and `Decide` handling |
-
----
-
-## References
-
-1. Plotkin, G.D. (1981). "A Structural Approach to Operational Semantics"
-2. Kahn, G. (1987). "Natural Semantics"
-3. Wright, A.K. and Felleisen, M. (1994). "A Syntactic Approach to Type Soundness"
+....
+
+*Proof:* Standard proof by induction on the structure of derivations,
+showing each big-step rule corresponds to a sequence of small-step
+transitions. □
+
+'''''
+
+=== 7. Reference Implementation Correspondence
+
+The operational semantics defined here corresponds directly to the
+tree-walking interpreter implementation in `+src/interpreter/mod.rs+`:
+
+[cols=",",options="header",]
+|===
+|Semantic Rule |Implementation
+|B-Var |`+Expr::Identifier+` case in `+evaluate()+`
+|B-BinOp |`+apply_binary_op()+` method
+|B-Call |`+call_function()+` method
+|B-VarDecl |`+Statement::VarDecl+` case in `+execute_statement()+`
+|B-If-* |`+Statement::Conditional+` case
+|B-Loop-* |`+Statement::Loop+` case
+|B-Consent-* |`+execute_consent_block()+` method
+|B-Match |`+pattern_matches()+` and `+Decide+` handling
+|===
+
+'''''
+
+=== References
+
+[arabic]
+. Plotkin, G.D. (1981). "`A Structural Approach to Operational
+Semantics`"
+. Kahn, G. (1987). "`Natural Semantics`"
+. Wright, A.K. and Felleisen, M. (1994). "`A Syntactic Approach to Type
+Soundness`"
diff --git a/docs/proofs/papers/language-design-whitepaper.adoc b/docs/proofs/papers/language-design-whitepaper.adoc
new file mode 100644
index 0000000..163a6dd
--- /dev/null
+++ b/docs/proofs/papers/language-design-whitepaper.adoc
@@ -0,0 +1,379 @@
+== WokeLang: A Consent-Driven, Human-Centered Programming Language
+
+*White Paper v1.0*
+
+=== Abstract
+
+WokeLang is a novel programming language that places human
+values—consent, attribution, and emotional context—at the center of its
+design. This paper presents the theoretical foundations, design
+rationale, and formal properties of WokeLang. We demonstrate how
+capability-based security with explicit consent enables fine-grained
+access control while maintaining usability. We prove type safety,
+describe the operational semantics, and compare WokeLang with existing
+approaches. WokeLang advances the state of programming language design
+by showing that human-centered computing principles can be formally
+specified and mechanically verified.
+
+=== 1. Introduction
+
+==== 1.1 Motivation
+
+Traditional programming languages treat security as an afterthought,
+bolting on permission systems after the core language is designed. This
+leads to ambient authority problems, confused deputy attacks, and user
+consent fatigue.
+
+WokeLang takes a different approach: *consent is a first-class language
+construct*. Every potentially sensitive operation requires explicit
+consent through the `+only if okay+` construct.
+
+==== 1.2 Design Principles
+
+[arabic]
+. *Explicit Consent*: No sensitive operation occurs without user
+awareness
+. *Gratitude as Attribution*: Credit flows through the codebase via
+`+thanks to+` blocks
+. *Emotional Context*: `+@emote+` tags capture developer intent
+. *Safety by Default*: The `+attempt safely+` construct provides
+graceful error handling
+. *Human-Readable Syntax*: Natural language keywords like `+remember+`,
+`+when+`, `+give back+`
+
+==== 1.3 Contributions
+
+This paper makes the following contributions: - A formal syntax and
+semantics for consent-driven programming - Proofs of type safety
+(Progress and Preservation) - A capability-based security model with
+formal guarantees - Multiple execution backends (interpreter, bytecode
+VM, WebAssembly) - Reference implementation in Rust
+
+=== 2. Language Overview
+
+==== 2.1 Syntax
+
+WokeLang uses natural language keywords:
+
+[source,wokelang]
+----
+thanks to {
+ "Alice" → "Core algorithm design";
+ "Bob" → "Performance optimization";
+}
+
+@important
+to greet(name: String) → String {
+ hello "Starting to greet";
+ remember message = "Hello, " + name + "!";
+ give back message;
+ goodbye "Greeting complete";
+}
+
+to main() {
+ only if okay "io:write:stdout" {
+ print(greet("World"));
+ }
+}
+----
+
+==== 2.2 Type System
+
+WokeLang features Hindley-Milner type inference with extensions:
+
+[cols=",",options="header",]
+|===
+|Type |Description
+|`+Int+` |64-bit signed integer
+|`+Float+` |64-bit floating point
+|`+String+` |UTF-8 string
+|`+Bool+` |Boolean
+|`+Unit+` |Unit type
+|`+[T]+` |Array of T
+|`+Maybe T+` |Optional T
+|`+Result[T, E]+` |Success T or Error E
+|`+(T₁,...,Tₙ) → R+` |Function type
+|===
+
+==== 2.3 Consent Model
+
+The `+only if okay "permission"+` construct gates sensitive operations:
+
+[source,wokelang]
+----
+only if okay "file:read:/etc/passwd" {
+ remember contents = readFile("/etc/passwd");
+}
+----
+
+Consent is: - *Interactive*: The user is prompted at runtime -
+*Cacheable*: Consent can be remembered for Session, Day, Week, or
+Forever - *Revocable*: Users can revoke consent at any time -
+*Auditable*: All consent decisions are logged
+
+=== 3. Formal Semantics
+
+==== 3.1 Operational Semantics
+
+We define big-step semantics with judgment `+⟨e, ρ, Φ, C⟩ ⇓ v+`:
+
+[cols=",",options="header",]
+|===
+|Component |Meaning
+|`+e+` |Expression
+|`+ρ+` |Value environment
+|`+Φ+` |Function store
+|`+C+` |Consent state
+|`+v+` |Resulting value
+|===
+
+Key rules:
+
+....
+[B-Consent-Grant]
+ perm ∈ C ⟨s*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
+───────────────────────────────────────────────────
+⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
+
+[B-Consent-Deny]
+ perm ∉ C
+───────────────────────────────────────────────────
+⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ, C)
+....
+
+==== 3.2 Denotational Semantics
+
+The denotational semantics assign mathematical meaning:
+
+....
+ℰ⟦e⟧ : Expr → Env → Consent → Value⊥
+𝒮⟦s⟧ : Stmt → Env → Consent → Cont → (Env × Consent × Ans)
+....
+
+==== 3.3 Type Safety
+
+*Theorem (Type Safety):* Well-typed programs don’t go wrong.
+
+....
+If ⊢ P : ok and ⟨P, ∅, Φ⟩ →* ⟨e, ρ, Φ⟩
+Then e is a value or ⟨e, ρ, Φ⟩ can step
+....
+
+The proof proceeds via Progress and Preservation lemmas (see
+type-theory/type-safety.md).
+
+=== 4. Security Model
+
+==== 4.1 Capability-Based Security
+
+WokeLang implements object-capability security:
+
+....
+Capability ::= FileRead(path?) | FileWrite(path?)
+ | Network(host?) | Execute(cmd?)
+ | Process | Crypto | ...
+....
+
+Capabilities are: - *Unforgeable*: Cannot be constructed except through
+consent - *Transferable*: Can be passed to functions (scope-based) -
+*Revocable*: Can be invalidated
+
+==== 4.2 Security Properties
+
+*No Privilege Escalation:* Programs cannot acquire capabilities beyond
+those granted.
+
+*Confinement:* Capabilities cannot leak between scopes without
+authorization.
+
+*Audit Completeness:* All capability operations are logged.
+
+See security/capability-proofs.md for formal proofs.
+
+=== 5. Implementation
+
+==== 5.1 Architecture
+
+....
+Source → Lexer → Parser → AST → Type Checker → Interpreter
+ ↘ Bytecode Compiler → VM
+ ↘ WASM Compiler → WebAssembly
+....
+
+==== 5.2 Execution Backends
+
+[cols=",,",options="header",]
+|===
+|Backend |Use Case |Performance
+|Tree-Walking Interpreter |Development, REPL |~100x native
+|Bytecode VM |Production |~20x native
+|WebAssembly |Browser, Edge |~2-5x native
+|===
+
+==== 5.3 Foreign Function Interface
+
+WokeLang provides C-compatible FFI:
+
+[source,c]
+----
+woke_interpreter_t* interp = woke_interpreter_new();
+woke_exec(interp, "to main() { print(\"Hello\"); }");
+woke_interpreter_free(interp);
+----
+
+=== 6. Comparison
+
+==== 6.1 vs. Python
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang |Python
+|Syntax |Natural language keywords |Traditional
+|Typing |Static with inference |Dynamic
+|Security |Capability-based consent |Ambient authority
+|Performance |Compiled |Interpreted
+|===
+
+==== 6.2 vs. Rust
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang |Rust
+|Memory Safety |Ownership (Rust backend) |Borrow checker
+|Security |Runtime consent |Compile-time
+|Learning Curve |Low |High
+|Target |Scripting, Applications |Systems
+|===
+
+==== 6.3 vs. JavaScript
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang |JavaScript
+|Type System |HM-style |Dynamic
+|Concurrency |Workers |Event loop, Workers
+|Security |Consent-based |Same-origin + CSP
+|Error Handling |Result types |Exceptions
+|===
+
+=== 7. Case Studies
+
+==== 7.1 File Processing Script
+
+[source,wokelang]
+----
+thanks to {
+ "User" → "Providing file access";
+}
+
+@cautious
+to processFile(path: String) → Result[String, String] {
+ only if okay "file:read:" + path {
+ remember content = readFile(path);
+ give back Okay(content);
+ }
+ give back Oops("Access denied");
+}
+
+to main() {
+ decide based on processFile("/data/input.txt") {
+ Okay(data) → {
+ print("Processed: " + data);
+ }
+ Oops(err) → {
+ complain err;
+ }
+ }
+}
+----
+
+==== 7.2 Web API Client
+
+[source,wokelang]
+----
+@experimental
+to fetchData(url: String) → Result[String, String] {
+ only if okay "network:connect:" + extractHost(url) {
+ give back httpGet(url);
+ }
+ give back Oops("Network access denied");
+}
+----
+
+=== 8. Future Work
+
+==== 8.1 Planned Features
+
+[arabic]
+. *Dependent Types*: Refinement types for bounds checking
+. *Linear Types*: Ensuring Result types are handled
+. *Effect System*: Tracking and controlling side effects
+. *Distributed Workers*: Cross-machine computation
+
+==== 8.2 Tooling
+
+[arabic]
+. *IDE Support*: LSP server, syntax highlighting
+. *Package Manager*: Dependency management with SHA-pinned packages
+. *Debugger*: Time-travel debugging
+. *Profiler*: Performance analysis
+
+==== 8.3 Formal Verification
+
+[arabic]
+. *Coq/Lean Proofs*: Complete mechanized verification
+. *Verified Compiler*: CompCert-style correctness
+. *Model Checking*: Temporal property verification
+
+=== 9. Conclusion
+
+WokeLang demonstrates that programming languages can embody human values
+without sacrificing rigor. By treating consent as a first-class concept,
+we enable fine-grained security while maintaining usability. Our formal
+semantics and type safety proofs ensure that these properties are not
+just aspirational but mathematically guaranteed.
+
+The reference implementation validates our design, and the multiple
+execution backends demonstrate practical utility. We invite the
+community to build upon this foundation.
+
+=== References
+
+[arabic]
+. Miller, M.S. (2006). "`Robust Composition: Towards a Unified Approach
+to Access Control and Concurrency Control`"
+. Pierce, B.C. (2002). "`Types and Programming Languages`"
+. Wadler, P. (2015). "`Propositions as Types`"
+. Dennis, J.B. and Van Horn, E.C. (1966). "`Programming Semantics for
+Multiprogrammed Computations`"
+. Milner, R. (1978). "`A Theory of Type Polymorphism in Programming`"
+. Plotkin, G.D. (1981). "`A Structural Approach to Operational
+Semantics`"
+. Wright, A.K. and Felleisen, M. (1994). "`A Syntactic Approach to Type
+Soundness`"
+. Leroy, X. (2009). "`Formal Verification of a Realistic Compiler`"
+
+=== Appendix A: Complete Grammar
+
+See docs/grammar.ebnf for the complete EBNF grammar specification.
+
+=== Appendix B: Proof Sketches
+
+==== B.1 Progress (Sketch)
+
+By induction on typing derivation. Each well-typed expression either: -
+Is a value (literals, arrays of values) - Can step (rules apply)
+
+The key insight is that stuck states only occur with undefined variables
+or type errors, which are ruled out by the typing judgment.
+
+==== B.2 Preservation (Sketch)
+
+By induction on typing derivation with case analysis on reduction rule.
+Substitution lemma ensures type preservation through β-reduction.
+
+=== Appendix C: Acknowledgments
+
+WokeLang draws inspiration from: - OCaml/ML for type inference - Rust
+for memory safety - E/Cap’n Proto for capability security - Python for
+readable syntax - Erlang for actor-based concurrency
diff --git a/docs/proofs/papers/language-design-whitepaper.md b/docs/proofs/papers/language-design-whitepaper.md
deleted file mode 100644
index fdd8beb..0000000
--- a/docs/proofs/papers/language-design-whitepaper.md
+++ /dev/null
@@ -1,335 +0,0 @@
-
-# WokeLang: A Consent-Driven, Human-Centered Programming Language
-
-**White Paper v1.0**
-
-## Abstract
-
-WokeLang is a novel programming language that places human values—consent, attribution, and emotional context—at the center of its design. This paper presents the theoretical foundations, design rationale, and formal properties of WokeLang. We demonstrate how capability-based security with explicit consent enables fine-grained access control while maintaining usability. We prove type safety, describe the operational semantics, and compare WokeLang with existing approaches. WokeLang advances the state of programming language design by showing that human-centered computing principles can be formally specified and mechanically verified.
-
-## 1. Introduction
-
-### 1.1 Motivation
-
-Traditional programming languages treat security as an afterthought, bolting on permission systems after the core language is designed. This leads to ambient authority problems, confused deputy attacks, and user consent fatigue.
-
-WokeLang takes a different approach: **consent is a first-class language construct**. Every potentially sensitive operation requires explicit consent through the `only if okay` construct.
-
-### 1.2 Design Principles
-
-1. **Explicit Consent**: No sensitive operation occurs without user awareness
-2. **Gratitude as Attribution**: Credit flows through the codebase via `thanks to` blocks
-3. **Emotional Context**: `@emote` tags capture developer intent
-4. **Safety by Default**: The `attempt safely` construct provides graceful error handling
-5. **Human-Readable Syntax**: Natural language keywords like `remember`, `when`, `give back`
-
-### 1.3 Contributions
-
-This paper makes the following contributions:
-- A formal syntax and semantics for consent-driven programming
-- Proofs of type safety (Progress and Preservation)
-- A capability-based security model with formal guarantees
-- Multiple execution backends (interpreter, bytecode VM, WebAssembly)
-- Reference implementation in Rust
-
-## 2. Language Overview
-
-### 2.1 Syntax
-
-WokeLang uses natural language keywords:
-
-```wokelang
-thanks to {
- "Alice" → "Core algorithm design";
- "Bob" → "Performance optimization";
-}
-
-@important
-to greet(name: String) → String {
- hello "Starting to greet";
- remember message = "Hello, " + name + "!";
- give back message;
- goodbye "Greeting complete";
-}
-
-to main() {
- only if okay "io:write:stdout" {
- print(greet("World"));
- }
-}
-```
-
-### 2.2 Type System
-
-WokeLang features Hindley-Milner type inference with extensions:
-
-| Type | Description |
-|------|-------------|
-| `Int` | 64-bit signed integer |
-| `Float` | 64-bit floating point |
-| `String` | UTF-8 string |
-| `Bool` | Boolean |
-| `Unit` | Unit type |
-| `[T]` | Array of T |
-| `Maybe T` | Optional T |
-| `Result[T, E]` | Success T or Error E |
-| `(T₁,...,Tₙ) → R` | Function type |
-
-### 2.3 Consent Model
-
-The `only if okay "permission"` construct gates sensitive operations:
-
-```wokelang
-only if okay "file:read:/etc/passwd" {
- remember contents = readFile("/etc/passwd");
-}
-```
-
-Consent is:
-- **Interactive**: The user is prompted at runtime
-- **Cacheable**: Consent can be remembered for Session, Day, Week, or Forever
-- **Revocable**: Users can revoke consent at any time
-- **Auditable**: All consent decisions are logged
-
-## 3. Formal Semantics
-
-### 3.1 Operational Semantics
-
-We define big-step semantics with judgment `⟨e, ρ, Φ, C⟩ ⇓ v`:
-
-| Component | Meaning |
-|-----------|---------|
-| `e` | Expression |
-| `ρ` | Value environment |
-| `Φ` | Function store |
-| `C` | Consent state |
-| `v` | Resulting value |
-
-Key rules:
-
-```
-[B-Consent-Grant]
- perm ∈ C ⟨s*, ρ, Φ, C⟩ ⇓ᵇ* (r, ρ', C')
-───────────────────────────────────────────────────
-⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (r, ρ', C')
-
-[B-Consent-Deny]
- perm ∉ C
-───────────────────────────────────────────────────
-⟨only if okay perm {s*}, ρ, Φ, C⟩ ⇓ᵇ (Continue, ρ, C)
-```
-
-### 3.2 Denotational Semantics
-
-The denotational semantics assign mathematical meaning:
-
-```
-ℰ⟦e⟧ : Expr → Env → Consent → Value⊥
-𝒮⟦s⟧ : Stmt → Env → Consent → Cont → (Env × Consent × Ans)
-```
-
-### 3.3 Type Safety
-
-**Theorem (Type Safety):** Well-typed programs don't go wrong.
-
-```
-If ⊢ P : ok and ⟨P, ∅, Φ⟩ →* ⟨e, ρ, Φ⟩
-Then e is a value or ⟨e, ρ, Φ⟩ can step
-```
-
-The proof proceeds via Progress and Preservation lemmas (see type-theory/type-safety.md).
-
-## 4. Security Model
-
-### 4.1 Capability-Based Security
-
-WokeLang implements object-capability security:
-
-```
-Capability ::= FileRead(path?) | FileWrite(path?)
- | Network(host?) | Execute(cmd?)
- | Process | Crypto | ...
-```
-
-Capabilities are:
-- **Unforgeable**: Cannot be constructed except through consent
-- **Transferable**: Can be passed to functions (scope-based)
-- **Revocable**: Can be invalidated
-
-### 4.2 Security Properties
-
-**No Privilege Escalation:** Programs cannot acquire capabilities beyond those granted.
-
-**Confinement:** Capabilities cannot leak between scopes without authorization.
-
-**Audit Completeness:** All capability operations are logged.
-
-See security/capability-proofs.md for formal proofs.
-
-## 5. Implementation
-
-### 5.1 Architecture
-
-```
-Source → Lexer → Parser → AST → Type Checker → Interpreter
- ↘ Bytecode Compiler → VM
- ↘ WASM Compiler → WebAssembly
-```
-
-### 5.2 Execution Backends
-
-| Backend | Use Case | Performance |
-|---------|----------|-------------|
-| Tree-Walking Interpreter | Development, REPL | ~100x native |
-| Bytecode VM | Production | ~20x native |
-| WebAssembly | Browser, Edge | ~2-5x native |
-
-### 5.3 Foreign Function Interface
-
-WokeLang provides C-compatible FFI:
-
-```c
-woke_interpreter_t* interp = woke_interpreter_new();
-woke_exec(interp, "to main() { print(\"Hello\"); }");
-woke_interpreter_free(interp);
-```
-
-## 6. Comparison
-
-### 6.1 vs. Python
-
-| Aspect | WokeLang | Python |
-|--------|----------|--------|
-| Syntax | Natural language keywords | Traditional |
-| Typing | Static with inference | Dynamic |
-| Security | Capability-based consent | Ambient authority |
-| Performance | Compiled | Interpreted |
-
-### 6.2 vs. Rust
-
-| Aspect | WokeLang | Rust |
-|--------|----------|------|
-| Memory Safety | Ownership (Rust backend) | Borrow checker |
-| Security | Runtime consent | Compile-time |
-| Learning Curve | Low | High |
-| Target | Scripting, Applications | Systems |
-
-### 6.3 vs. JavaScript
-
-| Aspect | WokeLang | JavaScript |
-|--------|----------|------------|
-| Type System | HM-style | Dynamic |
-| Concurrency | Workers | Event loop, Workers |
-| Security | Consent-based | Same-origin + CSP |
-| Error Handling | Result types | Exceptions |
-
-## 7. Case Studies
-
-### 7.1 File Processing Script
-
-```wokelang
-thanks to {
- "User" → "Providing file access";
-}
-
-@cautious
-to processFile(path: String) → Result[String, String] {
- only if okay "file:read:" + path {
- remember content = readFile(path);
- give back Okay(content);
- }
- give back Oops("Access denied");
-}
-
-to main() {
- decide based on processFile("/data/input.txt") {
- Okay(data) → {
- print("Processed: " + data);
- }
- Oops(err) → {
- complain err;
- }
- }
-}
-```
-
-### 7.2 Web API Client
-
-```wokelang
-@experimental
-to fetchData(url: String) → Result[String, String] {
- only if okay "network:connect:" + extractHost(url) {
- give back httpGet(url);
- }
- give back Oops("Network access denied");
-}
-```
-
-## 8. Future Work
-
-### 8.1 Planned Features
-
-1. **Dependent Types**: Refinement types for bounds checking
-2. **Linear Types**: Ensuring Result types are handled
-3. **Effect System**: Tracking and controlling side effects
-4. **Distributed Workers**: Cross-machine computation
-
-### 8.2 Tooling
-
-1. **IDE Support**: LSP server, syntax highlighting
-2. **Package Manager**: Dependency management with SHA-pinned packages
-3. **Debugger**: Time-travel debugging
-4. **Profiler**: Performance analysis
-
-### 8.3 Formal Verification
-
-1. **Coq/Lean Proofs**: Complete mechanized verification
-2. **Verified Compiler**: CompCert-style correctness
-3. **Model Checking**: Temporal property verification
-
-## 9. Conclusion
-
-WokeLang demonstrates that programming languages can embody human values without sacrificing rigor. By treating consent as a first-class concept, we enable fine-grained security while maintaining usability. Our formal semantics and type safety proofs ensure that these properties are not just aspirational but mathematically guaranteed.
-
-The reference implementation validates our design, and the multiple execution backends demonstrate practical utility. We invite the community to build upon this foundation.
-
-## References
-
-1. Miller, M.S. (2006). "Robust Composition: Towards a Unified Approach to Access Control and Concurrency Control"
-2. Pierce, B.C. (2002). "Types and Programming Languages"
-3. Wadler, P. (2015). "Propositions as Types"
-4. Dennis, J.B. and Van Horn, E.C. (1966). "Programming Semantics for Multiprogrammed Computations"
-5. Milner, R. (1978). "A Theory of Type Polymorphism in Programming"
-6. Plotkin, G.D. (1981). "A Structural Approach to Operational Semantics"
-7. Wright, A.K. and Felleisen, M. (1994). "A Syntactic Approach to Type Soundness"
-8. Leroy, X. (2009). "Formal Verification of a Realistic Compiler"
-
-## Appendix A: Complete Grammar
-
-See docs/grammar.ebnf for the complete EBNF grammar specification.
-
-## Appendix B: Proof Sketches
-
-### B.1 Progress (Sketch)
-
-By induction on typing derivation. Each well-typed expression either:
-- Is a value (literals, arrays of values)
-- Can step (rules apply)
-
-The key insight is that stuck states only occur with undefined variables or type errors, which are ruled out by the typing judgment.
-
-### B.2 Preservation (Sketch)
-
-By induction on typing derivation with case analysis on reduction rule. Substitution lemma ensures type preservation through β-reduction.
-
-## Appendix C: Acknowledgments
-
-WokeLang draws inspiration from:
-- OCaml/ML for type inference
-- Rust for memory safety
-- E/Cap'n Proto for capability security
-- Python for readable syntax
-- Erlang for actor-based concurrency
diff --git a/docs/proofs/papers/language-design-whitepaper.md.invariants.adoc b/docs/proofs/papers/language-design-whitepaper.md.invariants.adoc
new file mode 100644
index 0000000..71927db
--- /dev/null
+++ b/docs/proofs/papers/language-design-whitepaper.md.invariants.adoc
@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0 # Invariant Path Scan:
+language-design-whitepaper.md
diff --git a/docs/proofs/papers/language-design-whitepaper.md.invariants.md b/docs/proofs/papers/language-design-whitepaper.md.invariants.md
deleted file mode 100644
index afbc43e..0000000
--- a/docs/proofs/papers/language-design-whitepaper.md.invariants.md
+++ /dev/null
@@ -1,7 +0,0 @@
-
-// SPDX-License-Identifier: CC-BY-SA-4.0
-# Invariant Path Scan: language-design-whitepaper.md
-
diff --git a/docs/proofs/security/capability-proofs.adoc b/docs/proofs/security/capability-proofs.adoc
new file mode 100644
index 0000000..1d77d58
--- /dev/null
+++ b/docs/proofs/security/capability-proofs.adoc
@@ -0,0 +1,425 @@
+== WokeLang Capability-Based Security Proofs
+
+This document provides formal proofs of security properties for
+WokeLang’s capability-based security system (Superpowers).
+
+=== 1. Capability Model
+
+==== 1.1 Capability Definition
+
+....
+c ∈ Capability ::= FileRead(path?)
+ | FileWrite(path?)
+ | Execute(cmd?)
+ | Network(host?)
+ | Environment(var?)
+ | Process
+ | SystemInfo
+ | Crypto
+ | Clipboard
+ | Notify
+ | Custom(name)
+....
+
+The optional parameters represent scoping: `+None+` means wildcard
+(all), `+Some(x)+` means specific resource x.
+
+==== 1.2 Capability Set
+
+....
+C ∈ CapabilitySet = ℘(Capability)
+....
+
+==== 1.3 Granted Capability
+
+....
+g ∈ GrantedCapability = {
+ capability: Capability,
+ granted_at: Timestamp,
+ expires_at: Option,
+ granted_by: Principal,
+ revoked: Bool
+}
+....
+
+==== 1.4 Validity Predicate
+
+....
+valid(g) = ¬g.revoked ∧ (g.expires_at = None ∨ now() < g.expires_at)
+....
+
+'''''
+
+=== 2. Capability Algebra
+
+==== 2.1 Subsumption Relation
+
+Capability c₁ subsumes c₂ (written c₁ ⊇ c₂) if possessing c₁ grants the
+rights of c₂.
+
+....
+FileRead(None) ⊇ FileRead(Some(p)) ∀p
+FileWrite(None) ⊇ FileWrite(Some(p)) ∀p
+Execute(None) ⊇ Execute(Some(c)) ∀c
+Network(None) ⊇ Network(Some(h)) ∀h
+Environment(None) ⊇ Environment(Some(v)) ∀v
+c ⊇ c (reflexivity)
+....
+
+==== 2.2 Subsumption Properties
+
+*Theorem 2.1 (Reflexivity):* ∀c. c ⊇ c
+
+*Theorem 2.2 (Transitivity):* If c₁ ⊇ c₂ and c₂ ⊇ c₃, then c₁ ⊇ c₃
+
+*Theorem 2.3 (Antisymmetry):* If c₁ ⊇ c₂ and c₂ ⊇ c₁, then c₁ = c₂
+
+*Proof:* The subsumption relation forms a partial order. Wildcard
+capabilities are maximal elements within their category. □
+
+==== 2.3 Capability Satisfaction
+
+A capability set C satisfies a required capability c (written C ⊨ c):
+
+....
+C ⊨ c ⟺ ∃c' ∈ C. c' ⊇ c
+....
+
+'''''
+
+=== 3. Security State Machine
+
+==== 3.1 Security State
+
+....
+σ ∈ SecurityState = {
+ registry: Scope → List,
+ pending: Set,
+ audit_log: List
+}
+....
+
+==== 3.2 Security Actions
+
+....
+a ∈ Action ::= Grant(scope, capability, principal)
+ | Revoke(scope, capability)
+ | Request(scope, capability)
+ | Use(scope, capability)
+ | Cleanup
+....
+
+==== 3.3 Transition Rules
+
+===== Grant
+
+....
+ g = GrantedCapability(c, now(), None, p, false)
+─────────────────────────────────────────────────────────────────── [S-Grant]
+⟨σ, Grant(s, c, p)⟩ → ⟨σ[registry(s) := σ.registry(s) ++ [g]], ()⟩
+....
+
+===== Revoke
+
+....
+ σ' = σ[registry(s) := map (λg. if g.capability = c then g[revoked := true] else g) σ.registry(s)]
+────────────────────────────────────────────────────────────────────────────────────────────────────────── [S-Revoke]
+⟨σ, Revoke(s, c)⟩ → ⟨σ', ()⟩
+....
+
+===== Request (Granted)
+
+....
+ σ.registry(s) ⊨ c ∨ σ.registry("*") ⊨ c
+────────────────────────────────────────────────── [S-Request-Grant]
+⟨σ, Request(s, c)⟩ → ⟨σ, Ok(())⟩
+....
+
+===== Request (Denied)
+
+....
+ σ.registry(s) ⊭ c ∧ σ.registry("*") ⊭ c
+────────────────────────────────────────────────── [S-Request-Deny]
+⟨σ, Request(s, c)⟩ → ⟨σ, Err(CapabilityNotGranted)⟩
+....
+
+'''''
+
+=== 4. Security Properties
+
+==== 4.1 No Privilege Escalation
+
+*Theorem 4.1 (No Privilege Escalation):* A program cannot acquire
+capabilities beyond those explicitly granted.
+
+*Formal Statement:* If σ₀ is the initial state and σ₀ →* σₙ via program
+execution (not including interactive consent), then:
+
+....
+∀s, c. σₙ.registry(s) ⊨ c → σ₀.registry(s) ⊨ c
+....
+
+*Proof:* By induction on the transition sequence. The only transitions
+that add capabilities are [S-Grant], which requires explicit principal
+authorization. Program execution (in non-interactive mode) cannot invoke
+Grant. □
+
+==== 4.2 Capability Confinement
+
+*Theorem 4.2 (Confinement):* Capabilities cannot be transferred between
+scopes without explicit authorization.
+
+*Formal Statement:* For distinct scopes s₁ ≠ s₂:
+
+....
+σ.registry(s₁) ⊨ c ∧ σ.registry(s₂) ⊭ c →
+ ∀σ'. σ →* σ' → (σ'.registry(s₂) ⊨ c → Grant(s₂, c, _) occurred)
+....
+
+*Proof:* By inspection of transition rules. [S-Grant] is the only rule
+that adds capabilities to a scope’s registry. □
+
+==== 4.3 Revocation Effectiveness
+
+*Theorem 4.3 (Revocation):* Once revoked, a capability cannot be used
+until re-granted.
+
+*Formal Statement:* If Revoke(s, c) transitions σ to σ’, then:
+
+....
+∀σ''. σ' →* σ'' → (σ''.registry(s) ⊨ c → Grant(s, c, _) occurred after revocation)
+....
+
+*Proof:* [S-Revoke] sets `+revoked := true+` on matching grants. The
+validity predicate `+valid(g)+` checks `+¬g.revoked+`, so the capability
+is no longer satisfied. Only [S-Grant] can add new valid grants. □
+
+==== 4.4 Temporal Safety
+
+*Theorem 4.4 (Temporal Safety):* Expired capabilities are not valid.
+
+*Formal Statement:*
+
+....
+g.expires_at = Some(t) ∧ now() > t → ¬valid(g)
+....
+
+*Proof:* Direct from the definition of `+valid(g)+`. □
+
+==== 4.5 Audit Completeness
+
+*Theorem 4.5 (Audit Completeness):* All capability operations are
+recorded in the audit log.
+
+*Formal Statement:* For every transition `+⟨σ, a⟩ → ⟨σ', _⟩+` where a
+involves capabilities:
+
+....
+∃e ∈ σ'.audit_log. e.action corresponds to a
+....
+
+*Proof:* By inspection of the implementation. Each capability operation
+calls `+self.audit()+`. □
+
+'''''
+
+=== 5. Information Flow Security
+
+==== 5.1 Security Labels
+
+WokeLang’s consent system can be viewed through an information flow
+lens:
+
+....
+L ∈ Label = {Low, High} (simplified two-point lattice)
+....
+
+==== 5.2 Consent as Declassification
+
+A consent block `+only if okay p { s }+` acts as a controlled
+declassification:
+
+....
+ p ∈ C Γ; C ⊢ s : τ @ L
+──────────────────────────────────────────── [T-Consent-Declass]
+Γ; C ⊢ only if okay p { s } : τ @ Low
+....
+
+==== 5.3 Non-Interference (Relative)
+
+*Theorem 5.1 (Relative Non-Interference):* Without consent,
+high-security data cannot flow to low-security outputs.
+
+For programs P without consent blocks:
+
+....
+P(I_H, I_L) ≈_L P(I'_H, I_L)
+....
+
+Where `+≈_L+` means indistinguishable at low security level.
+
+*TODO:* Full formal proof requires defining the security type system.
+See `+verification/information-flow.v+` stub.
+
+'''''
+
+=== 6. Access Control Model
+
+==== 6.1 RBAC Mapping
+
+WokeLang’s scope-based capabilities map to Role-Based Access Control:
+
+....
+Role ≈ Scope (function name or "*")
+Permission ≈ Capability
+Subject ≈ Currently executing code
+Object ≈ Protected resource
+....
+
+==== 6.2 ABAC Extension
+
+The capability system supports Attribute-Based Access Control via: -
+Time-based expiry (temporal attributes) - Path-based file access
+(resource attributes) - Host-based network access (resource attributes)
+
+==== 6.3 Least Privilege
+
+*Theorem 6.1 (Least Privilege Support):* The capability model supports
+least-privilege execution.
+
+*Proof:* 1. Capabilities can be scoped to specific resources (path,
+command, host) 2. Capabilities can be time-limited via expiry 3.
+Capabilities are scope-specific (function-level granularity) 4. No
+implicit capability grants exist
+
+This provides the mechanisms for least-privilege; enforcement depends on
+usage. □
+
+'''''
+
+=== 7. Attack Resistance
+
+==== 7.1 Confused Deputy Prevention
+
+*Theorem 7.1:* WokeLang’s capability model prevents confused deputy
+attacks.
+
+*Proof:* - Capabilities are checked at the point of use, not the point
+of origin - Scope-based lookup means called functions use their own
+capabilities, not callers’ - The consent prompt includes the requesting
+scope for user verification □
+
+==== 7.2 TOCTOU Prevention
+
+*Theorem 7.2:* The capability check-then-use is atomic.
+
+*Proof:* The `+request+` method in the CapabilityRegistry performs check
+and grant atomically (in single-threaded context). In the current
+implementation, there’s no TOCTOU window. □
+
+*Note:* For concurrent execution, additional synchronization would be
+needed. See `+concurrency/worker-safety.md+`.
+
+==== 7.3 Ambient Authority Elimination
+
+*Theorem 7.3:* WokeLang eliminates ambient authority.
+
+*Proof:* - All sensitive operations require explicit capability checks -
+No operation succeeds based on implicit permissions - Environment access
+requires Environment capability - Process spawning requires Process
+capability □
+
+'''''
+
+=== 8. Formal Model in Logic
+
+==== 8.1 Authorization Logic
+
+We can express capability properties in an authorization logic:
+
+....
+Principal says Capability @ Scope
+....
+
+For example:
+
+....
+User says FileRead("/tmp") @ main
+User says Network(*) @ *
+....
+
+==== 8.2 Policy Language
+
+Capability policies can be expressed as:
+
+....
+policy ::= principal says capability @ scope [expires time]
+ | revoke capability @ scope
+ | if condition then policy
+....
+
+==== 8.3 Policy Evaluation
+
+....
+⟦principal says c @ s⟧σ = Grant(s, c, principal)
+⟦revoke c @ s⟧σ = Revoke(s, c)
+⟦if e then p⟧σ = if ⟦e⟧ then ⟦p⟧σ else id
+....
+
+'''''
+
+=== 9. Implementation Correspondence
+
+[width="100%",cols="28%,72%",options="header",]
+|===
+|Proof Concept |Implementation (`+src/security/mod.rs+`)
+|Capability |`+Capability+` enum
+
+|CapabilitySet
+|`+capabilities: HashMap>+`
+
+|Subsumption |`+capability_matches()+` method
+
+|Grant |`+grant()+` method
+
+|Revoke |`+revoke()+` method
+
+|Request |`+request()+` method
+
+|Validity |`+is_valid()+` method on GrantedCapability
+
+|Audit |`+audit()+` method, `+audit_log+` field
+|===
+
+'''''
+
+=== 10. Known Limitations and Future Work
+
+==== 10.1 Current Limitations
+
+[arabic]
+. *Single-threaded assumption:* Current proofs assume single-threaded
+execution
+. *Interactive consent:* Proofs don’t cover user interaction dynamics
+. *Persistence:* Consent persistence (`+consent.rs+`) not formally
+verified
+. *Covert channels:* Not analyzed
+
+==== 10.2 TODO: Extensions
+
+*TODO:* Formal verification of: - Thread-safe capability registry -
+Secure consent UI interaction - Persistent consent store integrity -
+Covert channel analysis
+
+'''''
+
+=== References
+
+[arabic]
+. Dennis, J.B. and Van Horn, E.C. (1966). "`Programming Semantics for
+Multiprogrammed Computations`"
+. Miller, M.S. et al. (2003). "`Capability Myths Demolished`"
+. Sabelfeld, A. and Myers, A.C. (2003). "`Language-Based
+Information-Flow Security`"
+. Saltzer, J.H. and Schroeder, M.D. (1975). "`The Protection of
+Information in Computer Systems`"
diff --git a/docs/proofs/security/capability-proofs.md b/docs/proofs/security/capability-proofs.md
deleted file mode 100644
index 53da2ec..0000000
--- a/docs/proofs/security/capability-proofs.md
+++ /dev/null
@@ -1,391 +0,0 @@
-
-# WokeLang Capability-Based Security Proofs
-
-This document provides formal proofs of security properties for WokeLang's capability-based security system (Superpowers).
-
-## 1. Capability Model
-
-### 1.1 Capability Definition
-
-```
-c ∈ Capability ::= FileRead(path?)
- | FileWrite(path?)
- | Execute(cmd?)
- | Network(host?)
- | Environment(var?)
- | Process
- | SystemInfo
- | Crypto
- | Clipboard
- | Notify
- | Custom(name)
-```
-
-The optional parameters represent scoping: `None` means wildcard (all), `Some(x)` means specific resource x.
-
-### 1.2 Capability Set
-
-```
-C ∈ CapabilitySet = ℘(Capability)
-```
-
-### 1.3 Granted Capability
-
-```
-g ∈ GrantedCapability = {
- capability: Capability,
- granted_at: Timestamp,
- expires_at: Option,
- granted_by: Principal,
- revoked: Bool
-}
-```
-
-### 1.4 Validity Predicate
-
-```
-valid(g) = ¬g.revoked ∧ (g.expires_at = None ∨ now() < g.expires_at)
-```
-
----
-
-## 2. Capability Algebra
-
-### 2.1 Subsumption Relation
-
-Capability c₁ subsumes c₂ (written c₁ ⊇ c₂) if possessing c₁ grants the rights of c₂.
-
-```
-FileRead(None) ⊇ FileRead(Some(p)) ∀p
-FileWrite(None) ⊇ FileWrite(Some(p)) ∀p
-Execute(None) ⊇ Execute(Some(c)) ∀c
-Network(None) ⊇ Network(Some(h)) ∀h
-Environment(None) ⊇ Environment(Some(v)) ∀v
-c ⊇ c (reflexivity)
-```
-
-### 2.2 Subsumption Properties
-
-**Theorem 2.1 (Reflexivity):** ∀c. c ⊇ c
-
-**Theorem 2.2 (Transitivity):** If c₁ ⊇ c₂ and c₂ ⊇ c₃, then c₁ ⊇ c₃
-
-**Theorem 2.3 (Antisymmetry):** If c₁ ⊇ c₂ and c₂ ⊇ c₁, then c₁ = c₂
-
-**Proof:** The subsumption relation forms a partial order. Wildcard capabilities are maximal elements within their category. □
-
-### 2.3 Capability Satisfaction
-
-A capability set C satisfies a required capability c (written C ⊨ c):
-
-```
-C ⊨ c ⟺ ∃c' ∈ C. c' ⊇ c
-```
-
----
-
-## 3. Security State Machine
-
-### 3.1 Security State
-
-```
-σ ∈ SecurityState = {
- registry: Scope → List,
- pending: Set,
- audit_log: List
-}
-```
-
-### 3.2 Security Actions
-
-```
-a ∈ Action ::= Grant(scope, capability, principal)
- | Revoke(scope, capability)
- | Request(scope, capability)
- | Use(scope, capability)
- | Cleanup
-```
-
-### 3.3 Transition Rules
-
-#### Grant
-
-```
- g = GrantedCapability(c, now(), None, p, false)
-─────────────────────────────────────────────────────────────────── [S-Grant]
-⟨σ, Grant(s, c, p)⟩ → ⟨σ[registry(s) := σ.registry(s) ++ [g]], ()⟩
-```
-
-#### Revoke
-
-```
- σ' = σ[registry(s) := map (λg. if g.capability = c then g[revoked := true] else g) σ.registry(s)]
-────────────────────────────────────────────────────────────────────────────────────────────────────────── [S-Revoke]
-⟨σ, Revoke(s, c)⟩ → ⟨σ', ()⟩
-```
-
-#### Request (Granted)
-
-```
- σ.registry(s) ⊨ c ∨ σ.registry("*") ⊨ c
-────────────────────────────────────────────────── [S-Request-Grant]
-⟨σ, Request(s, c)⟩ → ⟨σ, Ok(())⟩
-```
-
-#### Request (Denied)
-
-```
- σ.registry(s) ⊭ c ∧ σ.registry("*") ⊭ c
-────────────────────────────────────────────────── [S-Request-Deny]
-⟨σ, Request(s, c)⟩ → ⟨σ, Err(CapabilityNotGranted)⟩
-```
-
----
-
-## 4. Security Properties
-
-### 4.1 No Privilege Escalation
-
-**Theorem 4.1 (No Privilege Escalation):** A program cannot acquire capabilities beyond those explicitly granted.
-
-**Formal Statement:** If σ₀ is the initial state and σ₀ →* σₙ via program execution (not including interactive consent), then:
-
-```
-∀s, c. σₙ.registry(s) ⊨ c → σ₀.registry(s) ⊨ c
-```
-
-**Proof:** By induction on the transition sequence. The only transitions that add capabilities are [S-Grant], which requires explicit principal authorization. Program execution (in non-interactive mode) cannot invoke Grant. □
-
-### 4.2 Capability Confinement
-
-**Theorem 4.2 (Confinement):** Capabilities cannot be transferred between scopes without explicit authorization.
-
-**Formal Statement:** For distinct scopes s₁ ≠ s₂:
-
-```
-σ.registry(s₁) ⊨ c ∧ σ.registry(s₂) ⊭ c →
- ∀σ'. σ →* σ' → (σ'.registry(s₂) ⊨ c → Grant(s₂, c, _) occurred)
-```
-
-**Proof:** By inspection of transition rules. [S-Grant] is the only rule that adds capabilities to a scope's registry. □
-
-### 4.3 Revocation Effectiveness
-
-**Theorem 4.3 (Revocation):** Once revoked, a capability cannot be used until re-granted.
-
-**Formal Statement:** If Revoke(s, c) transitions σ to σ', then:
-
-```
-∀σ''. σ' →* σ'' → (σ''.registry(s) ⊨ c → Grant(s, c, _) occurred after revocation)
-```
-
-**Proof:** [S-Revoke] sets `revoked := true` on matching grants. The validity predicate `valid(g)` checks `¬g.revoked`, so the capability is no longer satisfied. Only [S-Grant] can add new valid grants. □
-
-### 4.4 Temporal Safety
-
-**Theorem 4.4 (Temporal Safety):** Expired capabilities are not valid.
-
-**Formal Statement:**
-
-```
-g.expires_at = Some(t) ∧ now() > t → ¬valid(g)
-```
-
-**Proof:** Direct from the definition of `valid(g)`. □
-
-### 4.5 Audit Completeness
-
-**Theorem 4.5 (Audit Completeness):** All capability operations are recorded in the audit log.
-
-**Formal Statement:** For every transition `⟨σ, a⟩ → ⟨σ', _⟩` where a involves capabilities:
-
-```
-∃e ∈ σ'.audit_log. e.action corresponds to a
-```
-
-**Proof:** By inspection of the implementation. Each capability operation calls `self.audit()`. □
-
----
-
-## 5. Information Flow Security
-
-### 5.1 Security Labels
-
-WokeLang's consent system can be viewed through an information flow lens:
-
-```
-L ∈ Label = {Low, High} (simplified two-point lattice)
-```
-
-### 5.2 Consent as Declassification
-
-A consent block `only if okay p { s }` acts as a controlled declassification:
-
-```
- p ∈ C Γ; C ⊢ s : τ @ L
-──────────────────────────────────────────── [T-Consent-Declass]
-Γ; C ⊢ only if okay p { s } : τ @ Low
-```
-
-### 5.3 Non-Interference (Relative)
-
-**Theorem 5.1 (Relative Non-Interference):** Without consent, high-security data cannot flow to low-security outputs.
-
-For programs P without consent blocks:
-
-```
-P(I_H, I_L) ≈_L P(I'_H, I_L)
-```
-
-Where `≈_L` means indistinguishable at low security level.
-
-**TODO:** Full formal proof requires defining the security type system. See `verification/information-flow.v` stub.
-
----
-
-## 6. Access Control Model
-
-### 6.1 RBAC Mapping
-
-WokeLang's scope-based capabilities map to Role-Based Access Control:
-
-```
-Role ≈ Scope (function name or "*")
-Permission ≈ Capability
-Subject ≈ Currently executing code
-Object ≈ Protected resource
-```
-
-### 6.2 ABAC Extension
-
-The capability system supports Attribute-Based Access Control via:
-- Time-based expiry (temporal attributes)
-- Path-based file access (resource attributes)
-- Host-based network access (resource attributes)
-
-### 6.3 Least Privilege
-
-**Theorem 6.1 (Least Privilege Support):** The capability model supports least-privilege execution.
-
-**Proof:**
-1. Capabilities can be scoped to specific resources (path, command, host)
-2. Capabilities can be time-limited via expiry
-3. Capabilities are scope-specific (function-level granularity)
-4. No implicit capability grants exist
-
-This provides the mechanisms for least-privilege; enforcement depends on usage. □
-
----
-
-## 7. Attack Resistance
-
-### 7.1 Confused Deputy Prevention
-
-**Theorem 7.1:** WokeLang's capability model prevents confused deputy attacks.
-
-**Proof:**
-- Capabilities are checked at the point of use, not the point of origin
-- Scope-based lookup means called functions use their own capabilities, not callers'
-- The consent prompt includes the requesting scope for user verification
-□
-
-### 7.2 TOCTOU Prevention
-
-**Theorem 7.2:** The capability check-then-use is atomic.
-
-**Proof:** The `request` method in the CapabilityRegistry performs check and grant atomically (in single-threaded context). In the current implementation, there's no TOCTOU window. □
-
-**Note:** For concurrent execution, additional synchronization would be needed. See `concurrency/worker-safety.md`.
-
-### 7.3 Ambient Authority Elimination
-
-**Theorem 7.3:** WokeLang eliminates ambient authority.
-
-**Proof:**
-- All sensitive operations require explicit capability checks
-- No operation succeeds based on implicit permissions
-- Environment access requires Environment capability
-- Process spawning requires Process capability
-□
-
----
-
-## 8. Formal Model in Logic
-
-### 8.1 Authorization Logic
-
-We can express capability properties in an authorization logic:
-
-```
-Principal says Capability @ Scope
-```
-
-For example:
-```
-User says FileRead("/tmp") @ main
-User says Network(*) @ *
-```
-
-### 8.2 Policy Language
-
-Capability policies can be expressed as:
-
-```
-policy ::= principal says capability @ scope [expires time]
- | revoke capability @ scope
- | if condition then policy
-```
-
-### 8.3 Policy Evaluation
-
-```
-⟦principal says c @ s⟧σ = Grant(s, c, principal)
-⟦revoke c @ s⟧σ = Revoke(s, c)
-⟦if e then p⟧σ = if ⟦e⟧ then ⟦p⟧σ else id
-```
-
----
-
-## 9. Implementation Correspondence
-
-| Proof Concept | Implementation (`src/security/mod.rs`) |
-|---------------|----------------------------------------|
-| Capability | `Capability` enum |
-| CapabilitySet | `capabilities: HashMap>` |
-| Subsumption | `capability_matches()` method |
-| Grant | `grant()` method |
-| Revoke | `revoke()` method |
-| Request | `request()` method |
-| Validity | `is_valid()` method on GrantedCapability |
-| Audit | `audit()` method, `audit_log` field |
-
----
-
-## 10. Known Limitations and Future Work
-
-### 10.1 Current Limitations
-
-1. **Single-threaded assumption:** Current proofs assume single-threaded execution
-2. **Interactive consent:** Proofs don't cover user interaction dynamics
-3. **Persistence:** Consent persistence (`consent.rs`) not formally verified
-4. **Covert channels:** Not analyzed
-
-### 10.2 TODO: Extensions
-
-**TODO:** Formal verification of:
-- Thread-safe capability registry
-- Secure consent UI interaction
-- Persistent consent store integrity
-- Covert channel analysis
-
----
-
-## References
-
-1. Dennis, J.B. and Van Horn, E.C. (1966). "Programming Semantics for Multiprogrammed Computations"
-2. Miller, M.S. et al. (2003). "Capability Myths Demolished"
-3. Sabelfeld, A. and Myers, A.C. (2003). "Language-Based Information-Flow Security"
-4. Saltzer, J.H. and Schroeder, M.D. (1975). "The Protection of Information in Computer Systems"
diff --git a/docs/proofs/security/consent-model.adoc b/docs/proofs/security/consent-model.adoc
new file mode 100644
index 0000000..fb59ad7
--- /dev/null
+++ b/docs/proofs/security/consent-model.adoc
@@ -0,0 +1,442 @@
+== WokeLang Consent Model: Formal Specification
+
+This document provides a complete formal specification of the consent
+system, including temporal logic properties, interactive semantics, and
+persistent storage proofs.
+
+=== 1. Consent Domain
+
+==== 1.1 Permission Language
+
+....
+π ∈ Permission ::= resource ":" action ":" target
+ | resource ":" action ":" "*"
+
+resource ∈ Resource ::= "file" | "network" | "execute" | "env" | "system" | "crypto"
+action ∈ Action ::= "read" | "write" | "connect" | "run" | "access"
+target ∈ Target ::= Path | Host | Command | Variable | "*"
+....
+
+Examples:
+
+....
+"file:read:/etc/passwd"
+"network:connect:api.example.com"
+"execute:run:*"
+....
+
+==== 1.2 Consent Duration
+
+....
+d ∈ Duration ::= Once (single use)
+ | Session (until program terminates)
+ | Day (24 hours from grant)
+ | Week (7 days from grant)
+ | Forever (no expiration)
+....
+
+==== 1.3 Stored Consent
+
+....
+consent ∈ StoredConsent = {
+ permission: Permission,
+ granted: Bool,
+ granted_at: Timestamp,
+ duration: Duration,
+ metadata: Map
+}
+....
+
+==== 1.4 Consent Store State
+
+....
+Σ ∈ ConsentStore = {
+ consents: Map,
+ file_path: Path,
+ dirty: Bool
+}
+....
+
+'''''
+
+=== 2. Consent Semantics
+
+==== 2.1 Validity Function
+
+....
+is_valid : StoredConsent × Timestamp → Bool
+is_valid(c, now) =
+ c.granted ∧
+ case c.duration of
+ Once → false -- Already used
+ Session → true -- Valid for session
+ Day → now - c.granted_at < 86400s
+ Week → now - c.granted_at < 604800s
+ Forever → true
+....
+
+==== 2.2 Lookup Semantics
+
+....
+lookup : ConsentStore × Permission × Timestamp → Option
+lookup(Σ, π, now) =
+ case Σ.consents.get(π) of
+ None → None -- No cached decision
+ Some(c) →
+ if is_valid(c, now) then Some(c.granted)
+ else None -- Expired
+....
+
+==== 2.3 Store Semantics
+
+....
+store : ConsentStore × Permission × Bool × Duration → ConsentStore
+store(Σ, π, granted, d) =
+ let c = {
+ permission: π,
+ granted: granted,
+ granted_at: now(),
+ duration: d,
+ metadata: {}
+ } in
+ Σ[consents := Σ.consents.insert(π, c)]
+ [dirty := true]
+....
+
+'''''
+
+=== 3. Interactive Consent Protocol
+
+==== 3.1 Protocol States
+
+....
+State ::= Initial
+ | Cached(result: Bool)
+ | Prompting
+ | Granted
+ | Denied
+ | Error(msg: String)
+....
+
+==== 3.2 Protocol Transitions
+
+....
+ lookup(Σ, π, now) = Some(b)
+────────────────────────────────────────── [P-Cached]
+⟨Initial, Σ, π⟩ → ⟨Cached(b), Σ, π⟩
+
+ lookup(Σ, π, now) = None
+────────────────────────────────────────── [P-NeedPrompt]
+⟨Initial, Σ, π⟩ → ⟨Prompting, Σ, π⟩
+
+ user_response = "y"
+────────────────────────────────────────── [P-UserGrant]
+⟨Prompting, Σ, π⟩ → ⟨Granted, store(Σ, π, true, Session), π⟩
+
+ user_response ≠ "y"
+────────────────────────────────────────── [P-UserDeny]
+⟨Prompting, Σ, π⟩ → ⟨Denied, store(Σ, π, false, Session), π⟩
+
+ Cached(true) ∨ Granted
+────────────────────────────────────────── [P-Allow]
+⟨_, Σ, π⟩ → execute protected operation
+
+ Cached(false) ∨ Denied
+────────────────────────────────────────── [P-Block]
+⟨_, Σ, π⟩ → skip protected operation
+....
+
+==== 3.3 Protocol Properties
+
+*Theorem 3.1 (Protocol Completeness):* Every consent request terminates
+in either Granted, Denied, Cached(true), or Cached(false).
+
+*Proof:* The protocol has no cycles: - Initial → Cached(_) or Initial →
+Prompting - Prompting → Granted or Prompting → Denied - All terminal
+states are decision states □
+
+*Theorem 3.2 (Determinism):* The consent protocol is deterministic given
+fixed user responses.
+
+*Proof:* Each state has exactly one outgoing transition for any given
+condition. The lookup function is deterministic. User responses are
+treated as external input. □
+
+'''''
+
+=== 4. Persistent Consent Store
+
+==== 4.1 Serialization Format
+
+....
+serialize : ConsentStore → Bytes
+deserialize : Bytes → Result
+....
+
+The on-disk format (TOML):
+
+[source,toml]
+----
+[consents."file:read:/tmp"]
+granted = true
+granted_at = 1704067200
+duration = "Session"
+----
+
+==== 4.2 Persistence Invariants
+
+*Invariant 4.1 (Round-Trip):* `+deserialize(serialize(Σ)) = Ok(Σ')+`
+where Σ ≈ Σ’ (semantically equivalent)
+
+*Invariant 4.2 (Crash Recovery):* If the program crashes after
+`+store()+` but before `+persist()+`, the store file remains consistent
+(possibly stale).
+
+*Invariant 4.3 (Atomic Write):* `+persist()+` uses atomic file
+operations (write-to-temp + rename).
+
+==== 4.3 File Integrity
+
+....
+persist : ConsentStore → IO>
+persist(Σ) =
+ let temp = Σ.file_path ++ ".tmp" in
+ let data = serialize(Σ) in
+ write_file(temp, data);
+ rename(temp, Σ.file_path);
+ Ok(())
+....
+
+*Theorem 4.1 (Persistence Safety):* The persist operation either fully
+succeeds or leaves the file unchanged.
+
+*Proof:* The rename operation is atomic on POSIX systems. If any step
+fails before rename, the original file is unmodified. □
+
+'''''
+
+=== 5. Security Properties
+
+==== 5.1 Consent Integrity
+
+*Theorem 5.1 (Consent Unforgability):* A program cannot create consent
+records without user interaction (in interactive mode).
+
+*Proof:* The only path to `+store(..., true, ...)+` in interactive mode
+goes through [P-UserGrant], which requires `+user_response = "y"+`. This
+is an external input. □
+
+==== 5.2 Consent Non-Repudiation
+
+*Theorem 5.2 (Audit Trail):* All consent decisions are recorded with
+timestamps.
+
+*Proof:* The `+store()+` function always sets `+granted_at: now()+`.
+Combined with the audit log in the capability system, all decisions are
+traceable. □
+
+==== 5.3 Temporal Consistency
+
+*Theorem 5.3 (Monotonic Time):* Consent validity is monotonically
+decreasing over time for time-limited consents.
+
+*Proof:* The `+is_valid()+` function computes
+`+now - granted_at < threshold+`. As `+now+` increases, this becomes
+false eventually for Day and Week durations. □
+
+==== 5.4 Privacy Protection
+
+*Theorem 5.4 (Consent Isolation):* Consent decisions for one permission
+do not affect other permissions.
+
+*Proof:* The consent store uses permission as key. `+lookup(Σ, π₁, _)+`
+and `+lookup(Σ, π₂, _)+` access different entries when π₁ ≠ π₂. □
+
+'''''
+
+=== 6. Formal Logic Encoding
+
+==== 6.1 Temporal Logic Properties
+
+Using LTL (Linear Temporal Logic):
+
+*Property 6.1 (Eventual Decision):*
+
+....
+G(request(π) → F(granted(π) ∨ denied(π)))
+....
+
+(Every request eventually gets a decision)
+
+*Property 6.2 (Consent Persistence):*
+
+....
+G(granted(π, Forever) → G(valid(π)))
+....
+
+(Forever grants remain valid)
+
+*Property 6.3 (Expiration):*
+
+....
+G(granted(π, Day) → F(¬valid(π)))
+....
+
+(Day grants eventually expire)
+
+==== 6.2 CTL Properties
+
+Using CTL (Computation Tree Logic):
+
+*Property 6.4 (Possibility of Grant):*
+
+....
+AG(request(π) → EF(granted(π)))
+....
+
+(It’s always possible to grant any request)
+
+*Property 6.5 (Possibility of Deny):*
+
+....
+AG(request(π) → EF(denied(π)))
+....
+
+(It’s always possible to deny any request)
+
+'''''
+
+=== 7. Consent UI Security
+
+==== 7.1 UI Spoofing Prevention
+
+*Requirement 7.1:* The consent prompt must be distinguishable from
+program output.
+
+*Implementation:* Uses system-level prefix `+🔐+` and different output
+stream (stderr vs stdout).
+
+==== 7.2 Clickjacking Prevention
+
+*Requirement 7.2:* Rapid successive consent requests should be
+throttled.
+
+*TODO:* Implement rate limiting for consent prompts:
+
+....
+throttle : Timestamp → IO<()>
+throttle(last_prompt) =
+ if now() - last_prompt < 500ms then
+ sleep(500ms - (now() - last_prompt))
+....
+
+==== 7.3 Phishing Resistance
+
+*Requirement 7.3:* Permission strings must be validated and normalized.
+
+....
+normalize : String → Permission
+normalize(s) =
+ let parts = s.split(':') in
+ if valid_resource(parts[0]) and valid_action(parts[1]) then
+ Permission { resource: parts[0], action: parts[1], target: parts[2] }
+ else
+ error("Invalid permission format")
+....
+
+'''''
+
+=== 8. Comparison with Other Models
+
+==== 8.1 vs. Android Permissions
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang Consent |Android Permissions
+|Granularity |Per-resource |Per-category
+|Timing |Runtime (JIT) |Install-time + Runtime
+|Revocation |Immediate |Requires app restart
+|Expiration |Configurable |None
+|Scope |Function-level |App-level
+|===
+
+==== 8.2 vs. Browser Permissions
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang Consent |Browser Permissions
+|Persistence |Configurable |Per-origin
+|UI |CLI prompt |Modal dialog
+|Categories |Extensible |Fixed set
+|Delegation |Scope-based |Not supported
+|===
+
+==== 8.3 vs. Capability Systems
+
+[cols=",,",options="header",]
+|===
+|Aspect |WokeLang Consent |Pure Capabilities
+|User Interaction |Required |Not required
+|Forgery Prevention |By protocol |By unforgability
+|Revocation |Explicit |Drop reference
+|Audit |Built-in |External
+|===
+
+'''''
+
+=== 9. Implementation Correspondence
+
+[cols=",",options="header",]
+|===
+|Concept |Implementation (`+src/security/consent.rs+`)
+|StoredConsent |`+StoredConsent+` struct
+|ConsentStore |`+ConsentStore+` struct
+|Duration |`+ConsentDuration+` enum
+|is_valid |`+is_valid()+` method
+|lookup |`+check()+` method
+|store |`+record()+` method
+|persist |`+save()+` method
+|deserialize |`+load()+` method
+|===
+
+'''''
+
+=== 10. Future Extensions
+
+==== 10.1 TODO: Delegation
+
+....
+delegate : Permission × Scope → Permission
+delegate(π, s) = π @ s
+....
+
+Allow functions to delegate subset of permissions to callees.
+
+==== 10.2 TODO: Composite Permissions
+
+....
+composite ::= π₁ ∧ π₂ (both required)
+ | π₁ ∨ π₂ (either sufficient)
+ | ¬π (negation)
+....
+
+==== 10.3 TODO: Policy Language
+
+....
+policy ::= allow π when condition
+ | deny π when condition
+ | ask π when condition
+....
+
+'''''
+
+=== References
+
+[arabic]
+. Arden, O. et al. (2015). "`Sharing Mobile Code Securely With
+Information Flow Control`"
+. Miller, M.S. (2006). "`Robust Composition: Towards a Unified Approach
+to Access Control`"
+. Felt, A.P. et al. (2012). "`Android Permissions: User Attention,
+Comprehension, and Behavior`"
+. Roesner, F. et al. (2012). "`User-Driven Access Control`"
diff --git a/docs/proofs/security/consent-model.md b/docs/proofs/security/consent-model.md
deleted file mode 100644
index 7f65266..0000000
--- a/docs/proofs/security/consent-model.md
+++ /dev/null
@@ -1,395 +0,0 @@
-
-# WokeLang Consent Model: Formal Specification
-
-This document provides a complete formal specification of the consent system, including temporal logic properties, interactive semantics, and persistent storage proofs.
-
-## 1. Consent Domain
-
-### 1.1 Permission Language
-
-```
-π ∈ Permission ::= resource ":" action ":" target
- | resource ":" action ":" "*"
-
-resource ∈ Resource ::= "file" | "network" | "execute" | "env" | "system" | "crypto"
-action ∈ Action ::= "read" | "write" | "connect" | "run" | "access"
-target ∈ Target ::= Path | Host | Command | Variable | "*"
-```
-
-Examples:
-```
-"file:read:/etc/passwd"
-"network:connect:api.example.com"
-"execute:run:*"
-```
-
-### 1.2 Consent Duration
-
-```
-d ∈ Duration ::= Once (single use)
- | Session (until program terminates)
- | Day (24 hours from grant)
- | Week (7 days from grant)
- | Forever (no expiration)
-```
-
-### 1.3 Stored Consent
-
-```
-consent ∈ StoredConsent = {
- permission: Permission,
- granted: Bool,
- granted_at: Timestamp,
- duration: Duration,
- metadata: Map
-}
-```
-
-### 1.4 Consent Store State
-
-```
-Σ ∈ ConsentStore = {
- consents: Map,
- file_path: Path,
- dirty: Bool
-}
-```
-
----
-
-## 2. Consent Semantics
-
-### 2.1 Validity Function
-
-```
-is_valid : StoredConsent × Timestamp → Bool
-is_valid(c, now) =
- c.granted ∧
- case c.duration of
- Once → false -- Already used
- Session → true -- Valid for session
- Day → now - c.granted_at < 86400s
- Week → now - c.granted_at < 604800s
- Forever → true
-```
-
-### 2.2 Lookup Semantics
-
-```
-lookup : ConsentStore × Permission × Timestamp → Option
-lookup(Σ, π, now) =
- case Σ.consents.get(π) of
- None → None -- No cached decision
- Some(c) →
- if is_valid(c, now) then Some(c.granted)
- else None -- Expired
-```
-
-### 2.3 Store Semantics
-
-```
-store : ConsentStore × Permission × Bool × Duration → ConsentStore
-store(Σ, π, granted, d) =
- let c = {
- permission: π,
- granted: granted,
- granted_at: now(),
- duration: d,
- metadata: {}
- } in
- Σ[consents := Σ.consents.insert(π, c)]
- [dirty := true]
-```
-
----
-
-## 3. Interactive Consent Protocol
-
-### 3.1 Protocol States
-
-```
-State ::= Initial
- | Cached(result: Bool)
- | Prompting
- | Granted
- | Denied
- | Error(msg: String)
-```
-
-### 3.2 Protocol Transitions
-
-```
- lookup(Σ, π, now) = Some(b)
-────────────────────────────────────────── [P-Cached]
-⟨Initial, Σ, π⟩ → ⟨Cached(b), Σ, π⟩
-
- lookup(Σ, π, now) = None
-────────────────────────────────────────── [P-NeedPrompt]
-⟨Initial, Σ, π⟩ → ⟨Prompting, Σ, π⟩
-
- user_response = "y"
-────────────────────────────────────────── [P-UserGrant]
-⟨Prompting, Σ, π⟩ → ⟨Granted, store(Σ, π, true, Session), π⟩
-
- user_response ≠ "y"
-────────────────────────────────────────── [P-UserDeny]
-⟨Prompting, Σ, π⟩ → ⟨Denied, store(Σ, π, false, Session), π⟩
-
- Cached(true) ∨ Granted
-────────────────────────────────────────── [P-Allow]
-⟨_, Σ, π⟩ → execute protected operation
-
- Cached(false) ∨ Denied
-────────────────────────────────────────── [P-Block]
-⟨_, Σ, π⟩ → skip protected operation
-```
-
-### 3.3 Protocol Properties
-
-**Theorem 3.1 (Protocol Completeness):** Every consent request terminates in either Granted, Denied, Cached(true), or Cached(false).
-
-**Proof:** The protocol has no cycles:
-- Initial → Cached(_) or Initial → Prompting
-- Prompting → Granted or Prompting → Denied
-- All terminal states are decision states □
-
-**Theorem 3.2 (Determinism):** The consent protocol is deterministic given fixed user responses.
-
-**Proof:** Each state has exactly one outgoing transition for any given condition. The lookup function is deterministic. User responses are treated as external input. □
-
----
-
-## 4. Persistent Consent Store
-
-### 4.1 Serialization Format
-
-```
-serialize : ConsentStore → Bytes
-deserialize : Bytes → Result
-```
-
-The on-disk format (TOML):
-```toml
-[consents."file:read:/tmp"]
-granted = true
-granted_at = 1704067200
-duration = "Session"
-```
-
-### 4.2 Persistence Invariants
-
-**Invariant 4.1 (Round-Trip):** `deserialize(serialize(Σ)) = Ok(Σ')` where Σ ≈ Σ' (semantically equivalent)
-
-**Invariant 4.2 (Crash Recovery):** If the program crashes after `store()` but before `persist()`, the store file remains consistent (possibly stale).
-
-**Invariant 4.3 (Atomic Write):** `persist()` uses atomic file operations (write-to-temp + rename).
-
-### 4.3 File Integrity
-
-```
-persist : ConsentStore → IO>
-persist(Σ) =
- let temp = Σ.file_path ++ ".tmp" in
- let data = serialize(Σ) in
- write_file(temp, data);
- rename(temp, Σ.file_path);
- Ok(())
-```
-
-**Theorem 4.1 (Persistence Safety):** The persist operation either fully succeeds or leaves the file unchanged.
-
-**Proof:** The rename operation is atomic on POSIX systems. If any step fails before rename, the original file is unmodified. □
-
----
-
-## 5. Security Properties
-
-### 5.1 Consent Integrity
-
-**Theorem 5.1 (Consent Unforgability):** A program cannot create consent records without user interaction (in interactive mode).
-
-**Proof:** The only path to `store(..., true, ...)` in interactive mode goes through [P-UserGrant], which requires `user_response = "y"`. This is an external input. □
-
-### 5.2 Consent Non-Repudiation
-
-**Theorem 5.2 (Audit Trail):** All consent decisions are recorded with timestamps.
-
-**Proof:** The `store()` function always sets `granted_at: now()`. Combined with the audit log in the capability system, all decisions are traceable. □
-
-### 5.3 Temporal Consistency
-
-**Theorem 5.3 (Monotonic Time):** Consent validity is monotonically decreasing over time for time-limited consents.
-
-**Proof:** The `is_valid()` function computes `now - granted_at < threshold`. As `now` increases, this becomes false eventually for Day and Week durations. □
-
-### 5.4 Privacy Protection
-
-**Theorem 5.4 (Consent Isolation):** Consent decisions for one permission do not affect other permissions.
-
-**Proof:** The consent store uses permission as key. `lookup(Σ, π₁, _)` and `lookup(Σ, π₂, _)` access different entries when π₁ ≠ π₂. □
-
----
-
-## 6. Formal Logic Encoding
-
-### 6.1 Temporal Logic Properties
-
-Using LTL (Linear Temporal Logic):
-
-**Property 6.1 (Eventual Decision):**
-```
-G(request(π) → F(granted(π) ∨ denied(π)))
-```
-(Every request eventually gets a decision)
-
-**Property 6.2 (Consent Persistence):**
-```
-G(granted(π, Forever) → G(valid(π)))
-```
-(Forever grants remain valid)
-
-**Property 6.3 (Expiration):**
-```
-G(granted(π, Day) → F(¬valid(π)))
-```
-(Day grants eventually expire)
-
-### 6.2 CTL Properties
-
-Using CTL (Computation Tree Logic):
-
-**Property 6.4 (Possibility of Grant):**
-```
-AG(request(π) → EF(granted(π)))
-```
-(It's always possible to grant any request)
-
-**Property 6.5 (Possibility of Deny):**
-```
-AG(request(π) → EF(denied(π)))
-```
-(It's always possible to deny any request)
-
----
-
-## 7. Consent UI Security
-
-### 7.1 UI Spoofing Prevention
-
-**Requirement 7.1:** The consent prompt must be distinguishable from program output.
-
-**Implementation:** Uses system-level prefix `🔐` and different output stream (stderr vs stdout).
-
-### 7.2 Clickjacking Prevention
-
-**Requirement 7.2:** Rapid successive consent requests should be throttled.
-
-**TODO:** Implement rate limiting for consent prompts:
-```
-throttle : Timestamp → IO<()>
-throttle(last_prompt) =
- if now() - last_prompt < 500ms then
- sleep(500ms - (now() - last_prompt))
-```
-
-### 7.3 Phishing Resistance
-
-**Requirement 7.3:** Permission strings must be validated and normalized.
-
-```
-normalize : String → Permission
-normalize(s) =
- let parts = s.split(':') in
- if valid_resource(parts[0]) and valid_action(parts[1]) then
- Permission { resource: parts[0], action: parts[1], target: parts[2] }
- else
- error("Invalid permission format")
-```
-
----
-
-## 8. Comparison with Other Models
-
-### 8.1 vs. Android Permissions
-
-| Aspect | WokeLang Consent | Android Permissions |
-|--------|------------------|---------------------|
-| Granularity | Per-resource | Per-category |
-| Timing | Runtime (JIT) | Install-time + Runtime |
-| Revocation | Immediate | Requires app restart |
-| Expiration | Configurable | None |
-| Scope | Function-level | App-level |
-
-### 8.2 vs. Browser Permissions
-
-| Aspect | WokeLang Consent | Browser Permissions |
-|--------|------------------|---------------------|
-| Persistence | Configurable | Per-origin |
-| UI | CLI prompt | Modal dialog |
-| Categories | Extensible | Fixed set |
-| Delegation | Scope-based | Not supported |
-
-### 8.3 vs. Capability Systems
-
-| Aspect | WokeLang Consent | Pure Capabilities |
-|--------|------------------|-------------------|
-| User Interaction | Required | Not required |
-| Forgery Prevention | By protocol | By unforgability |
-| Revocation | Explicit | Drop reference |
-| Audit | Built-in | External |
-
----
-
-## 9. Implementation Correspondence
-
-| Concept | Implementation (`src/security/consent.rs`) |
-|---------|---------------------------------------------|
-| StoredConsent | `StoredConsent` struct |
-| ConsentStore | `ConsentStore` struct |
-| Duration | `ConsentDuration` enum |
-| is_valid | `is_valid()` method |
-| lookup | `check()` method |
-| store | `record()` method |
-| persist | `save()` method |
-| deserialize | `load()` method |
-
----
-
-## 10. Future Extensions
-
-### 10.1 TODO: Delegation
-
-```
-delegate : Permission × Scope → Permission
-delegate(π, s) = π @ s
-```
-
-Allow functions to delegate subset of permissions to callees.
-
-### 10.2 TODO: Composite Permissions
-
-```
-composite ::= π₁ ∧ π₂ (both required)
- | π₁ ∨ π₂ (either sufficient)
- | ¬π (negation)
-```
-
-### 10.3 TODO: Policy Language
-
-```
-policy ::= allow π when condition
- | deny π when condition
- | ask π when condition
-```
-
----
-
-## References
-
-1. Arden, O. et al. (2015). "Sharing Mobile Code Securely With Information Flow Control"
-2. Miller, M.S. (2006). "Robust Composition: Towards a Unified Approach to Access Control"
-3. Felt, A.P. et al. (2012). "Android Permissions: User Attention, Comprehension, and Behavior"
-4. Roesner, F. et al. (2012). "User-Driven Access Control"
diff --git a/docs/proofs/type-theory/category-theory-foundations.md b/docs/proofs/type-theory/category-theory-foundations.adoc
similarity index 53%
rename from docs/proofs/type-theory/category-theory-foundations.md
rename to docs/proofs/type-theory/category-theory-foundations.adoc
index ac2eb12..5cbcf92 100644
--- a/docs/proofs/type-theory/category-theory-foundations.md
+++ b/docs/proofs/type-theory/category-theory-foundations.adoc
@@ -1,92 +1,91 @@
-
-# Category Theory Foundations for WokeLang
+== Category Theory Foundations for WokeLang
-This document provides the category-theoretic foundations underlying WokeLang's type system and semantics.
+This document provides the category-theoretic foundations underlying
+WokeLang’s type system and semantics.
-## 1. Categories and Types
+=== 1. Categories and Types
-### 1.1 The Category of Types
+==== 1.1 The Category of Types
-WokeLang types form a category **WokeType** where:
+WokeLang types form a category *WokeType* where:
-- **Objects:** Types (Int, Float, String, Bool, Unit, [τ], Maybe τ, Result[τ,ε], (τ₁,...,τₙ) → τ)
-- **Morphisms:** Type-preserving functions (terms of function type)
-- **Identity:** λx.x : τ → τ
-- **Composition:** (g ∘ f)(x) = g(f(x))
+* *Objects:* Types (Int, Float, String, Bool, Unit, [τ], Maybe τ,
+Result[τ,ε], (τ₁,…,τₙ) → τ)
+* *Morphisms:* Type-preserving functions (terms of function type)
+* *Identity:* λx.x : τ → τ
+* *Composition:* (g ∘ f)(x) = g(f(x))
-### 1.2 Categorical Constructs
+==== 1.2 Categorical Constructs
-#### 1.2.1 Terminal Object
+===== 1.2.1 Terminal Object
-```
+....
Unit (𝟙) is the terminal object:
∀τ. ∃! unit : τ → Unit
-```
+....
-The unique morphism to Unit is `λ_.unit`.
+The unique morphism to Unit is `+λ_.unit+`.
-#### 1.2.2 Initial Object
+===== 1.2.2 Initial Object
-```
+....
⊥ (bottom/void) is the initial object:
∀τ. ∃! absurd : ⊥ → τ
-```
+....
-WokeLang doesn't have an explicit void type, but runtime errors can be viewed as ⊥.
+WokeLang doesn’t have an explicit void type, but runtime errors can be
+viewed as ⊥.
-#### 1.2.3 Products
+===== 1.2.3 Products
-```
+....
τ₁ × τ₂ = { x: τ₁, y: τ₂ } (record types)
π₁ : τ₁ × τ₂ → τ₁
π₂ : τ₁ × τ₂ → τ₂
⟨f, g⟩ : σ → τ₁ × τ₂ when f : σ → τ₁ and g : σ → τ₂
-```
+....
-#### 1.2.4 Coproducts
+===== 1.2.4 Coproducts
-```
+....
τ₁ + τ₂ = Variant1(τ₁) | Variant2(τ₂) (sum types)
ι₁ : τ₁ → τ₁ + τ₂
ι₂ : τ₂ → τ₁ + τ₂
[f, g] : τ₁ + τ₂ → σ when f : τ₁ → σ and g : τ₂ → σ
-```
+....
-#### 1.2.5 Exponentials
+===== 1.2.5 Exponentials
-```
+....
τ₂^τ₁ = τ₁ → τ₂ (function types)
eval : (τ₂^τ₁) × τ₁ → τ₂
curry : (σ × τ₁ → τ₂) → (σ → τ₂^τ₁)
-```
+....
-**Theorem 1.1:** WokeType is a cartesian closed category (CCC).
+*Theorem 1.1:* WokeType is a cartesian closed category (CCC).
----
+'''''
-## 2. Functors
+=== 2. Functors
-### 2.1 The Array Functor
+==== 2.1 The Array Functor
-`[-] : WokeType → WokeType` is a functor:
+`+[-] : WokeType → WokeType+` is a functor:
-```
+....
Objects: τ ↦ [τ]
Morphisms: (f : τ₁ → τ₂) ↦ (map f : [τ₁] → [τ₂])
Functor Laws:
map id = id
map (g ∘ f) = map g ∘ map f
-```
+....
-### 2.2 The Maybe Functor
+==== 2.2 The Maybe Functor
-`Maybe : WokeType → WokeType` is a functor:
+`+Maybe : WokeType → WokeType+` is a functor:
-```
+....
Objects: τ ↦ Maybe τ
Morphisms: (f : τ₁ → τ₂) ↦ (fmap f : Maybe τ₁ → Maybe τ₂)
where fmap f Nothing = Nothing
@@ -95,28 +94,29 @@ Morphisms: (f : τ₁ → τ₂) ↦ (fmap f : Maybe τ₁ → Maybe τ₂)
Functor Laws:
fmap id = id
fmap (g ∘ f) = fmap g ∘ fmap f
-```
+....
-### 2.3 The Result Functor
+==== 2.3 The Result Functor
-For fixed error type ε, `Result[-, ε] : WokeType → WokeType` is a functor:
+For fixed error type ε, `+Result[-, ε] : WokeType → WokeType+` is a
+functor:
-```
+....
Objects: τ ↦ Result[τ, ε]
Morphisms: (f : τ₁ → τ₂) ↦ (fmap f : Result[τ₁, ε] → Result[τ₂, ε])
where fmap f (Oops e) = Oops e
fmap f (Okay x) = Okay (f x)
-```
+....
----
+'''''
-## 3. Monads
+=== 3. Monads
-### 3.1 The Maybe Monad
+==== 3.1 The Maybe Monad
Maybe forms a monad with:
-```
+....
η (return) : τ → Maybe τ
η x = Just x
@@ -128,48 +128,49 @@ Maybe forms a monad with:
(>>=) : Maybe τ₁ → (τ₁ → Maybe τ₂) → Maybe τ₂
Nothing >>= f = Nothing
Just x >>= f = f x
-```
+....
-**Monad Laws:**
-```
+*Monad Laws:*
+
+....
η x >>= f = f x (left identity)
m >>= η = m (right identity)
(m >>= f) >>= g = m >>= (λx. f x >>= g) (associativity)
-```
+....
-### 3.2 The Result Monad
+==== 3.2 The Result Monad
Result[τ, ε] forms a monad for fixed ε:
-```
+....
η : τ → Result[τ, ε]
η x = Okay x
(>>=) : Result[τ₁, ε] → (τ₁ → Result[τ₂, ε]) → Result[τ₂, ε]
Oops e >>= f = Oops e
Okay x >>= f = f x
-```
+....
-This is the basis for `attempt safely` and the `?` operator.
+This is the basis for `+attempt safely+` and the `+?+` operator.
-### 3.3 The State Monad
+==== 3.3 The State Monad
The interpreter can be viewed through the State monad:
-```
+....
State s a = s → (a, s)
η x = λs. (x, s)
m >>= f = λs. let (a, s') = m s in f a s'
-```
+....
Where s = (Environment, Consent, FunctionStore).
-### 3.4 The Consent Monad
+==== 3.4 The Consent Monad
We can define a Consent monad:
-```
+....
Consent a = ConsentState → (a + Denied, ConsentState)
η x = λc. (Okay x, c)
@@ -178,44 +179,47 @@ m >>= f = λc.
case r of
Oops e → (Oops e, c')
Okay a → f a c'
-```
+....
-### 3.5 Monad Transformers
+==== 3.5 Monad Transformers
Complex effects combine via transformers:
-```
+....
ExceptT ε (StateT s IO) a
= s → IO (Either ε a, s)
-```
+....
For WokeLang:
-```
+
+....
WokeM a = ConsentT (ResultT String (StateT Env IO)) a
-```
+....
----
+'''''
-## 4. Algebraic Data Types
+=== 4. Algebraic Data Types
-### 4.1 Polynomial Functors
+==== 4.1 Polynomial Functors
WokeLang ADTs are polynomial functors:
-```
+....
data List a = Nil | Cons a (List a)
ListF a x = 1 + a × x
List a = μx. ListF a x = μx. 1 + a × x
-```
+....
-### 4.2 Initial Algebras
+==== 4.2 Initial Algebras
-**Definition:** An F-algebra is a pair (A, α : F A → A).
+*Definition:* An F-algebra is a pair (A, α : F A → A).
-**Definition:** An initial F-algebra is an F-algebra (μF, in : F(μF) → μF) such that for any F-algebra (A, α), there exists a unique morphism (catamorphism) ⦇α⦈ : μF → A.
+*Definition:* An initial F-algebra is an F-algebra (μF, in : F(μF) → μF)
+such that for any F-algebra (A, α), there exists a unique morphism
+(catamorphism) ⦇α⦈ : μF → A.
-```
+....
F ⦇α⦈
F(μF) ────────→ F A
│ │
@@ -223,223 +227,232 @@ in│ │α
↓ ↓
μF ─────────→ A
⦇α⦈
-```
+....
-### 4.3 Catamorphisms (Folds)
+==== 4.3 Catamorphisms (Folds)
For List:
-```
+
+....
foldr : (a → b → b) → b → [a] → b
foldr f z [] = z
foldr f z (x:xs) = f x (foldr f z xs)
-```
+....
This is the catamorphism for the List functor.
----
+'''''
-## 5. Natural Transformations
+=== 5. Natural Transformations
-### 5.1 Definition
+==== 5.1 Definition
-A natural transformation η : F ⟹ G between functors F, G : C → D is a family of morphisms:
+A natural transformation η : F ⟹ G between functors F, G : C → D is a
+family of morphisms:
-```
+....
ηₐ : F(A) → G(A)
-```
+....
Such that for all f : A → B:
-```
+
+....
G(f) ∘ ηₐ = η_B ∘ F(f)
-```
+....
-### 5.2 Examples in WokeLang
+==== 5.2 Examples in WokeLang
-#### Maybe to Result
+===== Maybe to Result
-```
+....
maybeToResult : ∀τ ε. Maybe τ → Result[τ, ε]
maybeToResult Nothing = Oops "Nothing"
maybeToResult (Just x) = Okay x
-```
+....
-#### Array to Maybe
+===== Array to Maybe
-```
+....
headMaybe : ∀τ. [τ] → Maybe τ
headMaybe [] = Nothing
headMaybe (x:_) = Just x
-```
+....
----
+'''''
-## 6. Adjunctions
+=== 6. Adjunctions
-### 6.1 Free-Forgetful Adjunction
+==== 6.1 Free-Forgetful Adjunction
The relationship between WokeLang and untyped evaluation:
-```
+....
Free : Set → WokeType
Forgetful : WokeType → Set
Free ⊣ Forgetful
-```
+....
-### 6.2 Currying Adjunction
+==== 6.2 Currying Adjunction
-```
+....
- × A ⊣ (-)^A
Hom(B × A, C) ≅ Hom(B, C^A)
-```
+....
This is the basis for curry/uncurry:
-```
+....
curry : ((A × B) → C) → (A → (B → C))
uncurry : (A → (B → C)) → ((A × B) → C)
-```
+....
----
+'''''
-## 7. Limits and Colimits
+=== 7. Limits and Colimits
-### 7.1 Limits
+==== 7.1 Limits
-**Theorem 7.1:** WokeType has all finite limits.
+*Theorem 7.1:* WokeType has all finite limits.
-- Products: Record types
-- Equalizers: Subtyping (limited)
-- Pullbacks: Intersection types (not implemented)
+* Products: Record types
+* Equalizers: Subtyping (limited)
+* Pullbacks: Intersection types (not implemented)
-### 7.2 Colimits
+==== 7.2 Colimits
-**Theorem 7.2:** WokeType has all finite colimits.
+*Theorem 7.2:* WokeType has all finite colimits.
-- Coproducts: Sum types (enums)
-- Coequalizers: Quotient types (not implemented)
-- Pushouts: (not implemented)
+* Coproducts: Sum types (enums)
+* Coequalizers: Quotient types (not implemented)
+* Pushouts: (not implemented)
----
+'''''
-## 8. Topos Structure
+=== 8. Topos Structure
-### 8.1 Subobject Classifier
+==== 8.1 Subobject Classifier
If WokeLang had a Bool type acting as Ω:
-```
+....
true : 1 → Bool
χₘ : A → Bool (characteristic function of subobject m)
-```
+....
For predicate P on type A:
-```
+
+....
{ x : A | P(x) } ←→ P : A → Bool
-```
+....
-### 8.2 Power Objects
+==== 8.2 Power Objects
-```
+....
℘(A) = A → Bool
-```
+....
Not directly representable in WokeLang without dependent types.
----
+'''''
-## 9. Yoneda Lemma
+=== 9. Yoneda Lemma
-### 9.1 Statement
+==== 9.1 Statement
For any functor F : C → Set and object A in C:
-```
+....
Nat(Hom(A, -), F) ≅ F(A)
-```
+....
-### 9.2 Application to Types
+==== 9.2 Application to Types
For WokeLang types:
-```
+
+....
∀R. (τ → R) → F R ≅ F τ
-```
+....
This underlies continuation-passing style transformations.
----
+'''''
-## 10. Semantics Categories
+=== 10. Semantics Categories
-### 10.1 The Category of Domains
+==== 10.1 The Category of Domains
For denotational semantics:
-- **Objects:** CPOs (complete partial orders) with ⊥
-- **Morphisms:** Continuous (Scott-continuous) functions
-- **Limits:** Bilimits exist for domain equations
+* *Objects:* CPOs (complete partial orders) with ⊥
+* *Morphisms:* Continuous (Scott-continuous) functions
+* *Limits:* Bilimits exist for domain equations
-### 10.2 Solving Domain Equations
+==== 10.2 Solving Domain Equations
-```
+....
Value ≅ Int + Float + String + Bool + 1 + Value* + (Value + String) + (Value →ᶜ Value⊥)
-```
+....
-Solved using:
-1. Bilimit construction
-2. Information systems
-3. Inverse limit construction
+Solved using: 1. Bilimit construction 2. Information systems 3. Inverse
+limit construction
----
+'''''
-## 11. Linear and Affine Types (Future)
+=== 11. Linear and Affine Types (Future)
-### 11.1 Linear Logic Interpretation
+==== 11.1 Linear Logic Interpretation
Future WokeLang could add linear types:
-```
+....
τ ⊗ σ : Linear tensor (both consumed)
τ & σ : Additive conjunction (choose one)
τ ⊕ σ : Additive disjunction (sum type)
!τ : Of course (unlimited use)
-```
+....
-### 11.2 Relevance to Resources
+==== 11.2 Relevance to Resources
-Linear types ensure resources (like Result values) are used exactly once:
+Linear types ensure resources (like Result values) are used exactly
+once:
-```
+....
remember r : !Result[A, E] = operation();
// r must be matched/unwrapped exactly once
-```
-
----
-
-## 12. Categorical Semantics Summary
-
-| WokeLang Construct | Categorical Concept |
-|-------------------|---------------------|
-| Types | Objects in CCC |
-| Functions | Morphisms (exponential) |
-| Unit | Terminal object |
-| Records | Products |
-| Enums | Coproducts |
-| Arrays | List functor (initial algebra) |
-| Maybe | Option monad |
-| Result | Error monad |
-| Consent blocks | Graded monad / Effect |
-| Type inference | Universal property |
-
----
-
-## References
-
-1. Mac Lane, S. (1971). "Categories for the Working Mathematician"
-2. Awodey, S. (2010). "Category Theory"
-3. Pierce, B.C. (1991). "Basic Category Theory for Computer Scientists"
-4. Barr, M. and Wells, C. (1990). "Category Theory for Computing Science"
-5. Wadler, P. (1992). "Monads for Functional Programming"
-6. Moggi, E. (1991). "Notions of Computation and Monads"
-7. Lambek, J. and Scott, P.J. (1986). "Introduction to Higher Order Categorical Logic"
+....
+
+'''''
+
+=== 12. Categorical Semantics Summary
+
+[cols=",",options="header",]
+|===
+|WokeLang Construct |Categorical Concept
+|Types |Objects in CCC
+|Functions |Morphisms (exponential)
+|Unit |Terminal object
+|Records |Products
+|Enums |Coproducts
+|Arrays |List functor (initial algebra)
+|Maybe |Option monad
+|Result |Error monad
+|Consent blocks |Graded monad / Effect
+|Type inference |Universal property
+|===
+
+'''''
+
+=== References
+
+[arabic]
+. Mac Lane, S. (1971). "`Categories for the Working Mathematician`"
+. Awodey, S. (2010). "`Category Theory`"
+. Pierce, B.C. (1991). "`Basic Category Theory for Computer Scientists`"
+. Barr, M. and Wells, C. (1990). "`Category Theory for Computing
+Science`"
+. Wadler, P. (1992). "`Monads for Functional Programming`"
+. Moggi, E. (1991). "`Notions of Computation and Monads`"
+. Lambek, J. and Scott, P.J. (1986). "`Introduction to Higher Order
+Categorical Logic`"
diff --git a/docs/proofs/type-theory/hindley-milner.md b/docs/proofs/type-theory/hindley-milner.adoc
similarity index 57%
rename from docs/proofs/type-theory/hindley-milner.md
rename to docs/proofs/type-theory/hindley-milner.adoc
index 015348f..9d41a5d 100644
--- a/docs/proofs/type-theory/hindley-milner.md
+++ b/docs/proofs/type-theory/hindley-milner.adoc
@@ -1,34 +1,32 @@
-
-# WokeLang Hindley-Milner Type Inference
+== WokeLang Hindley-Milner Type Inference
-This document formalizes the type inference algorithm used in WokeLang, based on the Hindley-Milner type system with extensions for Result types.
+This document formalizes the type inference algorithm used in WokeLang,
+based on the Hindley-Milner type system with extensions for Result
+types.
-## 1. Type Language
+=== 1. Type Language
-### 1.1 Monotypes
+==== 1.1 Monotypes
-```
+....
τ ∈ Monotype ::= α (type variable)
| Int | Float | String | Bool | Unit
| [τ] (array type)
| Maybe τ (optional type)
| Result[τ, τ] (result type)
| (τ₁,...,τₙ) → τ (function type)
-```
+....
-### 1.2 Type Schemes (Polytypes)
+==== 1.2 Type Schemes (Polytypes)
-```
+....
σ ∈ TypeScheme ::= τ (monotype)
| ∀α.σ (universal quantification)
-```
+....
-### 1.3 Free Type Variables
+==== 1.3 Free Type Variables
-```
+....
FTV(α) = {α}
FTV(Int) = FTV(Float) = FTV(String) = FTV(Bool) = FTV(Unit) = ∅
FTV([τ]) = FTV(τ)
@@ -37,23 +35,23 @@ FTV(Result[τ₁, τ₂]) = FTV(τ₁) ∪ FTV(τ₂)
FTV((τ₁,...,τₙ) → τ) = FTV(τ₁) ∪ ... ∪ FTV(τₙ) ∪ FTV(τ)
FTV(∀α.σ) = FTV(σ) \ {α}
FTV(Γ) = ⋃{FTV(σ) | x:σ ∈ Γ}
-```
+....
----
+'''''
-## 2. Substitutions
+=== 2. Substitutions
-### 2.1 Definition
+==== 2.1 Definition
A substitution S is a finite mapping from type variables to types:
-```
+....
S : TypeVar ⇀ Monotype
-```
+....
-### 2.2 Application
+==== 2.2 Application
-```
+....
S(α) = S(α) if α ∈ dom(S), else α
S(Int) = Int, etc.
S([τ]) = [S(τ)]
@@ -62,37 +60,37 @@ S(Result[τ₁, τ₂]) = Result[S(τ₁), S(τ₂)]
S((τ₁,...,τₙ) → τ) = (S(τ₁),...,S(τₙ)) → S(τ)
S(∀α.σ) = ∀α.S\{α}(σ)
S(Γ) = {x : S(σ) | x:σ ∈ Γ}
-```
+....
-### 2.3 Composition
+==== 2.3 Composition
-```
+....
(S₁ ∘ S₂)(α) = S₁(S₂(α))
-```
+....
-### 2.4 Identity
+==== 2.4 Identity
-```
+....
id = ∅ (empty substitution)
-```
+....
----
+'''''
-## 3. Unification
+=== 3. Unification
-### 3.1 Most General Unifier (MGU)
+==== 3.1 Most General Unifier (MGU)
-The unification algorithm computes the most general unifier of two types.
+The unification algorithm computes the most general unifier of two
+types.
-**Definition:** S is a unifier of τ₁ and τ₂ if S(τ₁) = S(τ₂).
+*Definition:* S is a unifier of τ₁ and τ₂ if S(τ₁) = S(τ₂).
-**Definition:** S is the MGU of τ₁ and τ₂ if:
-1. S unifies τ₁ and τ₂
-2. For any other unifier S', there exists S'' such that S' = S'' ∘ S
+*Definition:* S is the MGU of τ₁ and τ₂ if: 1. S unifies τ₁ and τ₂ 2.
+For any other unifier S’, there exists S’’ such that S’ = S’’ ∘ S
-### 3.2 Unification Algorithm
+==== 3.2 Unification Algorithm
-```
+....
unify(τ, τ) = id
unify(α, τ) =
@@ -121,67 +119,71 @@ unify((τ₁,...,τₙ) → τ, (τ'₁,...,τ'ₙ) → τ') =
Sᵣ ∘ Sₙ ∘ ... ∘ S₁
unify(_, _) = fail
-```
+....
-### 3.3 Unification Properties
+==== 3.3 Unification Properties
-**Theorem 3.1 (Correctness):** If `unify(τ₁, τ₂) = S`, then `S(τ₁) = S(τ₂)`.
+*Theorem 3.1 (Correctness):* If `+unify(τ₁, τ₂) = S+`, then
+`+S(τ₁) = S(τ₂)+`.
-**Theorem 3.2 (Most General):** If `unify(τ₁, τ₂) = S` and S' also unifies τ₁ and τ₂, then there exists S'' such that S' = S'' ∘ S.
+*Theorem 3.2 (Most General):* If `+unify(τ₁, τ₂) = S+` and S’ also
+unifies τ₁ and τ₂, then there exists S’’ such that S’ = S’’ ∘ S.
-**Theorem 3.3 (Termination):** The unification algorithm terminates on all inputs.
+*Theorem 3.3 (Termination):* The unification algorithm terminates on all
+inputs.
-**Proof:** The size of types strictly decreases in recursive calls, and the occurs check prevents infinite types. □
+*Proof:* The size of types strictly decreases in recursive calls, and
+the occurs check prevents infinite types. □
-**Theorem 3.4 (Decidability):** Unifiability is decidable.
+*Theorem 3.4 (Decidability):* Unifiability is decidable.
----
+'''''
-## 4. Algorithm W
+=== 4. Algorithm W
Algorithm W is the core type inference algorithm for WokeLang.
-### 4.1 Instantiation
+==== 4.1 Instantiation
-```
+....
inst(∀α₁...αₙ.τ) = [α₁ ↦ β₁, ..., αₙ ↦ βₙ](τ)
where β₁,...,βₙ are fresh type variables
-```
+....
-### 4.2 Generalization
+==== 4.2 Generalization
-```
+....
gen(Γ, τ) = ∀α₁...αₙ.τ
where {α₁,...,αₙ} = FTV(τ) \ FTV(Γ)
-```
+....
-### 4.3 Algorithm W Definition
+==== 4.3 Algorithm W Definition
-```
+....
W(Γ, e) → (S, τ) -- Returns substitution and inferred type
-```
+....
-#### Literals
+===== Literals
-```
+....
W(Γ, n) = (id, Int) where n is integer literal
W(Γ, f) = (id, Float) where f is float literal
W(Γ, s) = (id, String) where s is string literal
W(Γ, true) = W(Γ, false) = (id, Bool)
W(Γ, unit) = (id, Unit)
-```
+....
-#### Variables
+===== Variables
-```
+....
W(Γ, x) =
if x ∉ dom(Γ) then fail "undefined variable"
else (id, inst(Γ(x)))
-```
+....
-#### Binary Operations
+===== Binary Operations
-```
+....
W(Γ, e₁ + e₂) =
let (S₁, τ₁) = W(Γ, e₁) in
let (S₂, τ₂) = W(S₁(Γ), e₂) in
@@ -191,11 +193,11 @@ W(Γ, e₁ + e₂) =
Float → (S₃ ∘ S₂ ∘ S₁, Float)
String → (S₃ ∘ S₂ ∘ S₁, String)
_ → fail "type error in +"
-```
+....
-#### Function Application
+===== Function Application
-```
+....
W(Γ, f(e₁,...,eₙ)) =
let σ = Γ(f) in
let (τ₁,...,τₙ) → τᵣ = inst(σ) in
@@ -205,30 +207,30 @@ W(Γ, f(e₁,...,eₙ)) =
let (Sₙ, τ'ₙ) = W(Uₙ₋₁ ∘ ... ∘ U₁ ∘ Sₙ₋₁ ∘ ... ∘ S₁(Γ), eₙ) in
let Uₙ = unify(Sₙ ∘ ... ∘ S₁(τₙ), τ'ₙ) in
(Uₙ ∘ Sₙ ∘ ... ∘ U₁ ∘ S₁, Uₙ ∘ ... ∘ U₁ ∘ Sₙ ∘ ... ∘ S₁(τᵣ))
-```
+....
-#### Lambda/Function Definition
+===== Lambda/Function Definition
-```
+....
W(Γ, λx.e) =
let α = fresh type variable in
let (S, τ) = W(Γ[x ↦ α], e) in
(S, S(α) → τ)
-```
+....
-#### Let Binding (remember)
+===== Let Binding (remember)
-```
+....
W(Γ, remember x = e₁; e₂) =
let (S₁, τ₁) = W(Γ, e₁) in
let σ = gen(S₁(Γ), τ₁) in
let (S₂, τ₂) = W(S₁(Γ)[x ↦ σ], e₂) in
(S₂ ∘ S₁, τ₂)
-```
+....
-#### Conditional
+===== Conditional
-```
+....
W(Γ, when e₁ { e₂ } otherwise { e₃ }) =
let (S₁, τ₁) = W(Γ, e₁) in
let U₁ = unify(τ₁, Bool) in
@@ -236,11 +238,11 @@ W(Γ, when e₁ { e₂ } otherwise { e₃ }) =
let (S₃, τ₃) = W(S₂ ∘ U₁ ∘ S₁(Γ), e₃) in
let U₂ = unify(S₃(τ₂), τ₃) in
(U₂ ∘ S₃ ∘ S₂ ∘ U₁ ∘ S₁, U₂(τ₃))
-```
+....
-#### Arrays
+===== Arrays
-```
+....
W(Γ, [e₁,...,eₙ]) =
if n = 0 then
let α = fresh in (id, [α])
@@ -250,11 +252,11 @@ W(Γ, [e₁,...,eₙ]) =
let (Sₙ, τₙ) = W(Sₙ₋₁ ∘ ... ∘ S₁(Γ), eₙ) in
let U = unifyAll(Sₙ ∘ ... ∘ S₂(τ₁), ..., τₙ) in
(U ∘ Sₙ ∘ ... ∘ S₁, [U(τₙ)])
-```
+....
-#### Result Constructors
+===== Result Constructors
-```
+....
W(Γ, Okay(e)) =
let (S, τ) = W(Γ, e) in
let α = fresh in
@@ -265,53 +267,55 @@ W(Γ, Oops(e)) =
let U = unify(τ, String) in
let α = fresh in
(U ∘ S, Result[α, String])
-```
+....
----
+'''''
-## 5. Soundness and Completeness
+=== 5. Soundness and Completeness
-### 5.1 Soundness
+==== 5.1 Soundness
-**Theorem 5.1 (Algorithm W Soundness):** If `W(Γ, e) = (S, τ)`, then `S(Γ) ⊢ e : τ`.
+*Theorem 5.1 (Algorithm W Soundness):* If `+W(Γ, e) = (S, τ)+`, then
+`+S(Γ) ⊢ e : τ+`.
-**Proof:** By structural induction on the expression e.
+*Proof:* By structural induction on the expression e.
-**Case e = x:**
-- W(Γ, x) = (id, inst(Γ(x)))
-- Γ(x) = σ and inst(σ) = τ where σ = ∀ᾱ.τ₀ and τ = τ₀[ᾱ ↦ β̄]
-- By [T-Var] and instantiation, Γ ⊢ x : τ ✓
+*Case e = x:* - W(Γ, x) = (id, inst(Γ(x))) - Γ(x) = σ and inst(σ) = τ
+where σ = ∀ᾱ.τ₀ and τ = τ₀[ᾱ ↦ β̄] - By [T-Var] and instantiation, Γ ⊢ x
+: τ ✓
-**Case e = e₁ + e₂:**
-- By IH, S₁(Γ) ⊢ e₁ : τ₁ and S₂S₁(Γ) ⊢ e₂ : τ₂
-- S₃ unifies S₂τ₁ and τ₂
-- By [T-Add-*], S₃S₂S₁(Γ) ⊢ e₁ + e₂ : S₃S₂τ₁ ✓
+*Case e = e₁ + e₂:* - By IH, S₁(Γ) ⊢ e₁ : τ₁ and S₂S₁(Γ) ⊢ e₂ : τ₂ - S₃
+unifies S₂τ₁ and τ₂ - By [T-Add-*], S₃S₂S₁(Γ) ⊢ e₁ + e₂ : S₃S₂τ₁ ✓
Other cases follow similarly by IH and the typing rules. □
-### 5.2 Completeness
+==== 5.2 Completeness
-**Theorem 5.2 (Algorithm W Completeness):** If `Γ ⊢ e : τ`, then `W(Γ, e) = (S, τ')` for some S, τ' such that there exists R with `R(τ') = τ` and `R ∘ S ≡ S` on FTV(Γ).
+*Theorem 5.2 (Algorithm W Completeness):* If `+Γ ⊢ e : τ+`, then
+`+W(Γ, e) = (S, τ')+` for some S, τ’ such that there exists R with
+`+R(τ') = τ+` and `+R ∘ S ≡ S+` on FTV(Γ).
-**Proof:** By structural induction on the typing derivation. The key insight is that W computes principal types. □
+*Proof:* By structural induction on the typing derivation. The key
+insight is that W computes principal types. □
-### 5.3 Principal Type Property
+==== 5.3 Principal Type Property
-**Theorem 5.3 (Principal Types):** If e is typeable in Γ, then W computes its principal type scheme.
+*Theorem 5.3 (Principal Types):* If e is typeable in Γ, then W computes
+its principal type scheme.
-**Definition:** σ is a principal type scheme of e in Γ if:
-1. Γ ⊢ e : σ
-2. For all σ' such that Γ ⊢ e : σ', we have σ' = S(σ) for some substitution S
+*Definition:* σ is a principal type scheme of e in Γ if: 1. Γ ⊢ e : σ 2.
+For all σ’ such that Γ ⊢ e : σ’, we have σ’ = S(σ) for some substitution
+S
----
+'''''
-## 6. Extensions for WokeLang
+=== 6. Extensions for WokeLang
-### 6.1 Result Type Inference
+==== 6.1 Result Type Inference
WokeLang extends standard HM with Result types:
-```
+....
W(Γ, decide based on e { Okay(x) → e₁; Oops(y) → e₂ }) =
let (S₁, τ) = W(Γ, e) in
let αok, αerr = fresh in
@@ -320,84 +324,96 @@ W(Γ, decide based on e { Okay(x) → e₁; Oops(y) → e₂ }) =
let (S₃, τ₂) = W(S₂U₁S₁(Γ)[y ↦ S₂U₁(αerr)], e₂) in
let U₂ = unify(S₃(τ₁), τ₂) in
(U₂ ∘ S₃ ∘ S₂ ∘ U₁ ∘ S₁, U₂(τ₂))
-```
+....
-### 6.2 Widening Rule
+==== 6.2 Widening Rule
WokeLang allows Int to widen to Float:
-```
+....
unify(Int, Float) = [promote]
unify(Float, Int) = [promote]
-```
+....
-This is implemented via a special "widening" substitution that doesn't fail but instead promotes Int to Float.
+This is implemented via a special "`widening`" substitution that doesn’t
+fail but instead promotes Int to Float.
-### 6.3 Type Annotations
+==== 6.3 Type Annotations
When explicit type annotations are provided:
-```
+....
W(Γ, remember x: τ = e) =
let (S, τ') = W(Γ, e) in
let U = unify(τ', τ) in
(U ∘ S, τ)
-```
+....
----
+'''''
-## 7. Complexity Analysis
+=== 7. Complexity Analysis
-### 7.1 Time Complexity
+==== 7.1 Time Complexity
-**Theorem 7.1:** Algorithm W runs in O(n²) time in the worst case, where n is the size of the expression.
+*Theorem 7.1:* Algorithm W runs in O(n²) time in the worst case, where n
+is the size of the expression.
-This is due to the occurs check in unification, which must traverse the entire type.
+This is due to the occurs check in unification, which must traverse the
+entire type.
-### 7.2 Space Complexity
+==== 7.2 Space Complexity
-**Theorem 7.2:** Algorithm W uses O(n) space for the substitution.
+*Theorem 7.2:* Algorithm W uses O(n) space for the substitution.
-### 7.3 Practical Performance
+==== 7.3 Practical Performance
-In practice, WokeLang programs have small types, and inference is nearly linear.
+In practice, WokeLang programs have small types, and inference is nearly
+linear.
----
+'''''
-## 8. Implementation Correspondence
+=== 8. Implementation Correspondence
-The algorithm corresponds to `src/typechecker/mod.rs`:
+The algorithm corresponds to `+src/typechecker/mod.rs+`:
-| Algorithm Component | Implementation |
-|---------------------|----------------|
-| Fresh type variable | `fresh_type_var()` method |
-| Unification | `unify()` method |
-| Substitution application | `apply_substitutions()` method |
-| Type environment | `TypeEnv` struct |
-| Inference | `infer_expr()` method |
-| AST to internal type | `ast_type_to_inferred()` method |
+[cols=",",options="header",]
+|===
+|Algorithm Component |Implementation
+|Fresh type variable |`+fresh_type_var()+` method
+|Unification |`+unify()+` method
+|Substitution application |`+apply_substitutions()+` method
+|Type environment |`+TypeEnv+` struct
+|Inference |`+infer_expr()+` method
+|AST to internal type |`+ast_type_to_inferred()+` method
+|===
----
+'''''
-## 9. Error Messages
+=== 9. Error Messages
When unification fails, WokeLang provides informative errors:
-```rust
+[source,rust]
+----
TypeError::TypeMismatch { expected, actual }
TypeError::ArityMismatch { expected, actual }
TypeError::UndefinedVariable(name)
TypeError::UndefinedFunction(name)
-```
+----
-**TODO:** Implement better error recovery and multi-error reporting.
+*TODO:* Implement better error recovery and multi-error reporting.
----
+'''''
-## References
+=== References
-1. Milner, R. (1978). "A Theory of Type Polymorphism in Programming"
-2. Damas, L. and Milner, R. (1982). "Principal Type-Schemes for Functional Programs"
-3. Hindley, R. (1969). "The Principal Type-Scheme of an Object in Combinatory Logic"
-4. Robinson, J.A. (1965). "A Machine-Oriented Logic Based on the Resolution Principle"
-5. Lee, O. and Yi, K. (1998). "Proofs about a Folklore Let-Polymorphic Type Inference Algorithm"
+[arabic]
+. Milner, R. (1978). "`A Theory of Type Polymorphism in Programming`"
+. Damas, L. and Milner, R. (1982). "`Principal Type-Schemes for
+Functional Programs`"
+. Hindley, R. (1969). "`The Principal Type-Scheme of an Object in
+Combinatory Logic`"
+. Robinson, J.A. (1965). "`A Machine-Oriented Logic Based on the
+Resolution Principle`"
+. Lee, O. and Yi, K. (1998). "`Proofs about a Folklore Let-Polymorphic
+Type Inference Algorithm`"
diff --git a/docs/proofs/type-theory/type-safety.adoc b/docs/proofs/type-theory/type-safety.adoc
new file mode 100644
index 0000000..b3d4097
--- /dev/null
+++ b/docs/proofs/type-theory/type-safety.adoc
@@ -0,0 +1,443 @@
+== WokeLang Type Safety Proofs
+
+This document provides formal proofs of type safety for the WokeLang
+type system, including the fundamental Progress and Preservation
+theorems.
+
+=== 1. Type System Definition
+
+==== 1.1 Types
+
+....
+τ ∈ Type ::= Int | Float | String | Bool | Unit
+ | [τ] (arrays)
+ | Maybe τ (optionals)
+ | Result[τ, τ] (result types)
+ | (τ₁,...,τₙ) → τ (function types)
+ | α (type variables)
+....
+
+==== 1.2 Type Environment
+
+....
+Γ ∈ TypeEnv = Ident → Type
+Φ ∈ FuncEnv = Ident → Type
+....
+
+==== 1.3 Typing Judgments
+
+Expression typing: `+Γ; Φ ⊢ e : τ+` Statement typing:
+`+Γ; Φ; τᵣ ⊢ s ⟹ Γ'+` Program typing: `+⊢ p : ok+`
+
+'''''
+
+=== 2. Typing Rules
+
+==== 2.1 Expression Typing
+
+===== Literals
+
+....
+─────────────────────── [T-Int]
+Γ; Φ ⊢ n : Int
+
+─────────────────────── [T-Float]
+Γ; Φ ⊢ f : Float
+
+─────────────────────── [T-String]
+Γ; Φ ⊢ s : String
+
+─────────────────────── [T-Bool]
+Γ; Φ ⊢ b : Bool
+
+─────────────────────── [T-Unit]
+Γ; Φ ⊢ unit : Unit
+....
+
+===== Variables
+
+....
+ Γ(x) = τ
+─────────────────────── [T-Var]
+Γ; Φ ⊢ x : τ
+....
+
+===== Binary Operations
+
+....
+Γ; Φ ⊢ e₁ : Int Γ; Φ ⊢ e₂ : Int
+────────────────────────────────────── [T-Add-Int]
+Γ; Φ ⊢ e₁ + e₂ : Int
+
+Γ; Φ ⊢ e₁ : Float Γ; Φ ⊢ e₂ : Float
+──────────────────────────────────────── [T-Add-Float]
+Γ; Φ ⊢ e₁ + e₂ : Float
+
+Γ; Φ ⊢ e₁ : Int Γ; Φ ⊢ e₂ : Float
+────────────────────────────────────── [T-Add-Promote]
+Γ; Φ ⊢ e₁ + e₂ : Float
+
+Γ; Φ ⊢ e₁ : String Γ; Φ ⊢ e₂ : String
+──────────────────────────────────────────── [T-Concat]
+Γ; Φ ⊢ e₁ + e₂ : String
+....
+
+Similar rules for `+-+`, `+*+`, `+/+`, `+%+`.
+
+===== Comparison Operations
+
+....
+Γ; Φ ⊢ e₁ : τ Γ; Φ ⊢ e₂ : τ τ ∈ {Int, Float, String}
+──────────────────────────────────────────────────────────── [T-Compare]
+Γ; Φ ⊢ e₁ < e₂ : Bool
+....
+
+Similar for `+>+`, `+<=+`, `+>=+`.
+
+....
+Γ; Φ ⊢ e₁ : τ Γ; Φ ⊢ e₂ : τ
+───────────────────────────────── [T-Eq]
+Γ; Φ ⊢ e₁ == e₂ : Bool
+....
+
+===== Logical Operations
+
+....
+Γ; Φ ⊢ e₁ : Bool Γ; Φ ⊢ e₂ : Bool
+────────────────────────────────────── [T-And]
+Γ; Φ ⊢ e₁ and e₂ : Bool
+
+Γ; Φ ⊢ e₁ : Bool Γ; Φ ⊢ e₂ : Bool
+────────────────────────────────────── [T-Or]
+Γ; Φ ⊢ e₁ or e₂ : Bool
+....
+
+===== Unary Operations
+
+....
+Γ; Φ ⊢ e : τ τ ∈ {Int, Float}
+───────────────────────────────── [T-Neg]
+Γ; Φ ⊢ -e : τ
+
+Γ; Φ ⊢ e : Bool
+──────────────────── [T-Not]
+Γ; Φ ⊢ not e : Bool
+....
+
+===== Function Calls
+
+....
+Φ(f) = (τ₁,...,τₙ) → τᵣ
+Γ; Φ ⊢ e₁ : τ₁ ... Γ; Φ ⊢ eₙ : τₙ
+────────────────────────────────────── [T-Call]
+Γ; Φ ⊢ f(e₁,...,eₙ) : τᵣ
+....
+
+===== Arrays
+
+....
+Γ; Φ ⊢ e₁ : τ ... Γ; Φ ⊢ eₙ : τ
+────────────────────────────────── [T-Array]
+Γ; Φ ⊢ [e₁,...,eₙ] : [τ]
+
+Γ; Φ ⊢ e₁ : [τ] Γ; Φ ⊢ e₂ : Int
+──────────────────────────────────── [T-Index]
+Γ; Φ ⊢ e₁[e₂] : τ
+....
+
+===== Result Types
+
+....
+Γ; Φ ⊢ e : τ
+────────────────────────────── [T-Okay]
+Γ; Φ ⊢ Okay(e) : Result[τ, String]
+
+Γ; Φ ⊢ e : String
+────────────────────────────── [T-Oops]
+Γ; Φ ⊢ Oops(e) : Result[τ, String]
+
+Γ; Φ ⊢ e : Result[τ, τₑ]
+────────────────────────── [T-Unwrap]
+Γ; Φ ⊢ unwrap e : τ
+
+Γ; Φ ⊢ e : Result[τ, τₑ]
+────────────────────────── [T-IsOkay]
+Γ; Φ ⊢ isOkay(e) : Bool
+....
+
+===== Unit Measurement
+
+....
+Γ; Φ ⊢ e : τ τ ∈ {Int, Float}
+───────────────────────────────── [T-Measure]
+Γ; Φ ⊢ e measured in u : τ
+....
+
+==== 2.2 Statement Typing
+
+....
+Γ; Φ ⊢ e : τ
+──────────────────────────────────── [T-VarDecl]
+Γ; Φ; τᵣ ⊢ remember x = e ⟹ Γ[x ↦ τ]
+
+Γ(x) = τ Γ; Φ ⊢ e : τ
+──────────────────────────────── [T-Assign]
+Γ; Φ; τᵣ ⊢ x = e ⟹ Γ
+
+Γ; Φ ⊢ e : τᵣ
+──────────────────────────── [T-Return]
+Γ; Φ; τᵣ ⊢ give back e ⟹ Γ
+
+Γ; Φ ⊢ e : Bool Γ; Φ; τᵣ ⊢ s₁* ⟹ Γ₁ Γ; Φ; τᵣ ⊢ s₂* ⟹ Γ₂
+──────────────────────────────────────────────────────────────── [T-If]
+Γ; Φ; τᵣ ⊢ when e {s₁*} otherwise {s₂*} ⟹ Γ
+
+Γ; Φ ⊢ e : Int Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
+──────────────────────────────────────── [T-Loop]
+Γ; Φ; τᵣ ⊢ repeat e times {s*} ⟹ Γ
+
+Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
+───────────────────────────────────────────────── [T-Attempt]
+Γ; Φ; τᵣ ⊢ attempt safely {s*} or reassure m ⟹ Γ
+
+Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
+───────────────────────────────────────── [T-Consent]
+Γ; Φ; τᵣ ⊢ only if okay p {s*} ⟹ Γ
+....
+
+==== 2.3 Function Typing
+
+....
+Γ₀ = [x₁ ↦ τ₁, ..., xₙ ↦ τₙ]
+Γ₀; Φ; τᵣ ⊢ body ⟹ Γ'
+────────────────────────────────────────────────────── [T-Func]
+Φ ⊢ to f(x₁:τ₁,...,xₙ:τₙ) → τᵣ { body } : (τ₁,...,τₙ) → τᵣ
+....
+
+'''''
+
+=== 3. Type Safety Theorems
+
+==== 3.1 Canonical Forms Lemma
+
+*Lemma 3.1 (Canonical Forms):* If `+⊢ v : τ+` and v is a value, then:
+
+[arabic]
+. If τ = Int, then v = n for some n ∈ ℤ
+. If τ = Float, then v = f for some f ∈ ℝ
+. If τ = String, then v = s for some string s
+. If τ = Bool, then v ∈ \{true, false}
+. If τ = Unit, then v = unit
+. If τ = [τ’], then v = [v₁,…,vₙ] where ⊢ vᵢ : τ’ for all i
+. If τ = Result[τ₁, τ₂], then v = Okay(v’) with ⊢ v’ : τ₁ or v = Oops(s)
+with ⊢ s : τ₂
+. If τ = (τ₁,…,τₙ) → τᵣ, then v is a closure
+
+*Proof:* By inspection of the typing rules and value forms. Each type
+has a unique set of value constructors. □
+
+==== 3.2 Progress Theorem
+
+*Theorem 3.2 (Progress):* If `+Γ; Φ ⊢ e : τ+` and e is closed (contains
+no free variables not in Γ), then either: 1. e is a value, or 2. There
+exists e’ such that `+⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩+`
+
+*Proof:* By structural induction on the typing derivation.
+
+*Case T-Int, T-Float, T-String, T-Bool, T-Unit:* e is already a value. ✓
+
+*Case T-Var:* `+e = x+` and `+Γ(x) = τ+`. Since e is closed, x ∈ dom(ρ),
+so `+⟨x, ρ, Φ⟩ → ⟨ρ(x), ρ, Φ⟩+` by [S-Var]. ✓
+
+*Case T-Add-Int:* `+e = e₁ + e₂+` with `+Γ; Φ ⊢ e₁ : Int+` and
+`+Γ; Φ ⊢ e₂ : Int+`. - By IH on e₁: either e₁ is a value or e₁ can step
+- If e₁ can step, then e can step by [S-Context] with E = □ + e₂ - If e₁
+is a value v₁, by IH on e₂: either e₂ is a value or e₂ can step - If e₂
+can step, then e can step by [S-Context] with E = v₁ + □ - If e₂ is a
+value v₂, by Canonical Forms, v₁ = n₁ and v₂ = n₂ for some integers -
+Then `+⟨n₁ + n₂, ρ, Φ⟩ → ⟨n₁ + n₂, ρ, Φ⟩+` by [S-BinOp] ✓
+
+*Case T-Call:* `+e = f(e₁,...,eₙ)+` with `+Φ(f) = (τ₁,...,τₙ) → τᵣ+` and
+`+Γ; Φ ⊢ eᵢ : τᵢ+`. - By IH, each eᵢ either is a value or can step - If
+any eᵢ can step, e can step by [S-Context] - If all eᵢ are values vᵢ,
+then by [S-Call], e steps to the function body with substituted
+parameters ✓
+
+*Case T-Index:* `+e = e₁[e₂]+` with `+Γ; Φ ⊢ e₁ : [τ]+` and
+`+Γ; Φ ⊢ e₂ : Int+`. - By IH on e₁ and e₂, both evaluate or step - If
+both are values, by Canonical Forms, e₁ = [v₀,…,vₖ] and e₂ = n - If 0 ≤
+n ≤ k, then e steps to vₙ by [S-Index] - If n < 0 or n > k, evaluation
+gets stuck (runtime error)
+
+*Note:* Array bounds checking is a runtime check, not a static type
+check. The type system guarantees type safety, not memory safety in the
+bounds-checking sense. □
+
+==== 3.3 Preservation Theorem
+
+*Theorem 3.3 (Preservation/Subject Reduction):* If `+Γ; Φ ⊢ e : τ+` and
+`+⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩+`, then `+Γ; Φ ⊢ e' : τ+`.
+
+*Proof:* By structural induction on the typing derivation, with case
+analysis on the reduction rule.
+
+*Case T-Var:* `+e = x+` with `+Γ(x) = τ+`. - The only applicable
+reduction is [S-Var]: `+⟨x, ρ, Φ⟩ → ⟨ρ(x), ρ, Φ⟩+` - We need
+`+Γ; Φ ⊢ ρ(x) : τ+` - This holds if the environment ρ is well-typed with
+respect to Γ (environment typing invariant) ✓
+
+*Case T-Add-Int:* `+e = e₁ + e₂+` with both typed as Int. - If
+`+e = n₁ + n₂+` (both values), reduction gives `+n₁ + n₂ = n₃ ∈ ℤ+`, and
+`+Γ; Φ ⊢ n₃ : Int+` by [T-Int] ✓ - If e₁ or e₂ steps, by IH and
+[T-Add-Int], the result is still typed Int ✓
+
+*Case T-Call:* `+e = f(v₁,...,vₙ)+` where all arguments are values. - By
+[S-Call]: e reduces to body[x₁ := v₁, …, xₙ := vₙ] - By [T-Func], the
+body is typed in environment `+[x₁ ↦ τ₁, ..., xₙ ↦ τₙ]+` with return
+type τᵣ - By Substitution Lemma (Lemma 3.4 below), substituting
+well-typed values preserves typing - Therefore
+`+Γ; Φ ⊢ body[x₁ := v₁, ..., xₙ := vₙ] : τᵣ+` ✓
+
+*Case T-Array:* `+e = [e₁,...,eₙ]+` with all eᵢ : τ. - If some eᵢ steps
+to e’ᵢ, by IH, `+Γ; Φ ⊢ e'ᵢ : τ+` - The array [e₁,…,e’ᵢ,…,eₙ] still has
+type [τ] by [T-Array] ✓
+
+*Case T-Index:* `+e = [v₀,...,vₖ][n]+` with array type [τ]. - By
+[S-Index], e reduces to vₙ (assuming 0 ≤ n ≤ k) - Since [v₀,…,vₖ] : [τ],
+each vᵢ : τ by inversion - Therefore vₙ : τ ✓
+
+□
+
+==== 3.4 Substitution Lemma
+
+*Lemma 3.4 (Substitution):* If `+Γ, x:τ'; Φ ⊢ e : τ+` and
+`+Γ; Φ ⊢ v : τ'+`, then `+Γ; Φ ⊢ e[x := v] : τ+`.
+
+*Proof:* By structural induction on the derivation of
+`+Γ, x:τ'; Φ ⊢ e : τ+`.
+
+*Case T-Var where e = x:* Then τ = τ’ and e[x := v] = v. By assumption,
+`+Γ; Φ ⊢ v : τ'+` = `+Γ; Φ ⊢ v : τ+`. ✓
+
+*Case T-Var where e = y ≠ x:* Then e[x := v] = y and
+`+(Γ, x:τ')(y) = τ = Γ(y)+`. By [T-Var], `+Γ; Φ ⊢ y : τ+`. ✓
+
+*Case T-Add-Int:* `+e = e₁ + e₂+` with both subexpressions typed Int. -
+By IH, `+Γ; Φ ⊢ e₁[x := v] : Int+` and `+Γ; Φ ⊢ e₂[x := v] : Int+` - By
+[T-Add-Int],
+`+Γ; Φ ⊢ (e₁ + e₂)[x := v] = e₁[x := v] + e₂[x := v] : Int+` ✓
+
+Other cases follow similarly by IH and applying the appropriate typing
+rule. □
+
+==== 3.5 Type Safety (Main Theorem)
+
+*Theorem 3.5 (Type Safety):* Well-typed programs don’t go wrong.
+
+If `+⊢ p : ok+` and `+⟨p, ∅, Φ⟩ →* ⟨e, ρ, Φ⟩+`, then either: 1. e is a
+value, or 2. There exists e’ such that `+⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩+`
+
+*Proof:* By induction on the number of reduction steps, using Progress
+and Preservation at each step. □
+
+'''''
+
+=== 4. Type Inference Properties
+
+==== 4.1 Principal Types
+
+*Theorem 4.1 (Principal Types):* If e is typeable, then e has a
+principal type scheme σ such that all types of e are instances of σ.
+
+This follows from the Hindley-Milner nature of WokeLang’s type system.
+See hindley-milner.md for the type inference algorithm.
+
+==== 4.2 Decidability
+
+*Theorem 4.2 (Decidability of Type Checking):* Type checking for
+WokeLang is decidable.
+
+*Proof:* The type inference algorithm (Algorithm W variant) terminates
+and produces a principal type or reports an error. □
+
+==== 4.3 Completeness
+
+*Theorem 4.3 (Completeness of Type Inference):* If e has a type, the
+inference algorithm finds it.
+
+'''''
+
+=== 5. Subtyping Properties
+
+WokeLang has limited subtyping for numeric types:
+
+==== 5.1 Subtyping Rules
+
+....
+─────────── [Sub-Refl]
+τ <: τ
+
+Int <: Float
+....
+
+==== 5.2 Subsumption
+
+....
+Γ; Φ ⊢ e : τ τ <: τ'
+──────────────────────── [T-Sub]
+Γ; Φ ⊢ e : τ'
+....
+
+==== 5.3 Subtyping Safety
+
+*Theorem 5.1 (Subtyping Safety):* If `+Γ; Φ ⊢ e : τ+` and `+τ <: τ'+`,
+then e can be safely used where τ’ is expected.
+
+*Proof:* The only non-trivial subtyping is Int <: Float. Integer
+operations produce integers, and integers can be safely widened to
+floats in contexts expecting floats. □
+
+'''''
+
+=== 6. Error Cases and Runtime Checks
+
+The type system does *not* prevent these runtime errors:
+
+[arabic]
+. *Array bounds errors:* `+[1,2,3][10]+` is well-typed as Int but fails
+at runtime
+. *Division by zero:* `+x / 0+` is well-typed but fails at runtime
+. *Unwrap of Oops:* `+unwrap Oops("error")+` is well-typed but fails at
+runtime
+
+*TODO:* These could be addressed with: - Dependent types for array
+bounds - Refinement types for non-zero divisors - Linear types for
+Result handling (see verification/future-work.md)
+
+'''''
+
+=== 7. Implementation Correspondence
+
+The proofs correspond to the implementation in
+`+src/typechecker/mod.rs+`:
+
+[cols=",",options="header",]
+|===
+|Theorem/Lemma |Implementation
+|Typing rules |`+infer_expr()+`, `+check_statement()+`
+|Unification |`+unify()+` method
+|Substitution |`+apply_substitutions()+` method
+|Type environment |`+TypeEnv+` struct
+|Error reporting |`+TypeError+` enum
+|===
+
+'''''
+
+=== References
+
+[arabic]
+. Wright, A.K. and Felleisen, M. (1994). "`A Syntactic Approach to Type
+Soundness`"
+. Pierce, B.C. (2002). "`Types and Programming Languages`"
+. Harper, R. (2016). "`Practical Foundations for Programming Languages`"
+. Milner, R. (1978). "`A Theory of Type Polymorphism in Programming`"
diff --git a/docs/proofs/type-theory/type-safety.md b/docs/proofs/type-theory/type-safety.md
deleted file mode 100644
index 1443ee8..0000000
--- a/docs/proofs/type-theory/type-safety.md
+++ /dev/null
@@ -1,415 +0,0 @@
-
-# WokeLang Type Safety Proofs
-
-This document provides formal proofs of type safety for the WokeLang type system, including the fundamental Progress and Preservation theorems.
-
-## 1. Type System Definition
-
-### 1.1 Types
-
-```
-τ ∈ Type ::= Int | Float | String | Bool | Unit
- | [τ] (arrays)
- | Maybe τ (optionals)
- | Result[τ, τ] (result types)
- | (τ₁,...,τₙ) → τ (function types)
- | α (type variables)
-```
-
-### 1.2 Type Environment
-
-```
-Γ ∈ TypeEnv = Ident → Type
-Φ ∈ FuncEnv = Ident → Type
-```
-
-### 1.3 Typing Judgments
-
-Expression typing: `Γ; Φ ⊢ e : τ`
-Statement typing: `Γ; Φ; τᵣ ⊢ s ⟹ Γ'`
-Program typing: `⊢ p : ok`
-
----
-
-## 2. Typing Rules
-
-### 2.1 Expression Typing
-
-#### Literals
-
-```
-─────────────────────── [T-Int]
-Γ; Φ ⊢ n : Int
-
-─────────────────────── [T-Float]
-Γ; Φ ⊢ f : Float
-
-─────────────────────── [T-String]
-Γ; Φ ⊢ s : String
-
-─────────────────────── [T-Bool]
-Γ; Φ ⊢ b : Bool
-
-─────────────────────── [T-Unit]
-Γ; Φ ⊢ unit : Unit
-```
-
-#### Variables
-
-```
- Γ(x) = τ
-─────────────────────── [T-Var]
-Γ; Φ ⊢ x : τ
-```
-
-#### Binary Operations
-
-```
-Γ; Φ ⊢ e₁ : Int Γ; Φ ⊢ e₂ : Int
-────────────────────────────────────── [T-Add-Int]
-Γ; Φ ⊢ e₁ + e₂ : Int
-
-Γ; Φ ⊢ e₁ : Float Γ; Φ ⊢ e₂ : Float
-──────────────────────────────────────── [T-Add-Float]
-Γ; Φ ⊢ e₁ + e₂ : Float
-
-Γ; Φ ⊢ e₁ : Int Γ; Φ ⊢ e₂ : Float
-────────────────────────────────────── [T-Add-Promote]
-Γ; Φ ⊢ e₁ + e₂ : Float
-
-Γ; Φ ⊢ e₁ : String Γ; Φ ⊢ e₂ : String
-──────────────────────────────────────────── [T-Concat]
-Γ; Φ ⊢ e₁ + e₂ : String
-```
-
-Similar rules for `-`, `*`, `/`, `%`.
-
-#### Comparison Operations
-
-```
-Γ; Φ ⊢ e₁ : τ Γ; Φ ⊢ e₂ : τ τ ∈ {Int, Float, String}
-──────────────────────────────────────────────────────────── [T-Compare]
-Γ; Φ ⊢ e₁ < e₂ : Bool
-```
-
-Similar for `>`, `<=`, `>=`.
-
-```
-Γ; Φ ⊢ e₁ : τ Γ; Φ ⊢ e₂ : τ
-───────────────────────────────── [T-Eq]
-Γ; Φ ⊢ e₁ == e₂ : Bool
-```
-
-#### Logical Operations
-
-```
-Γ; Φ ⊢ e₁ : Bool Γ; Φ ⊢ e₂ : Bool
-────────────────────────────────────── [T-And]
-Γ; Φ ⊢ e₁ and e₂ : Bool
-
-Γ; Φ ⊢ e₁ : Bool Γ; Φ ⊢ e₂ : Bool
-────────────────────────────────────── [T-Or]
-Γ; Φ ⊢ e₁ or e₂ : Bool
-```
-
-#### Unary Operations
-
-```
-Γ; Φ ⊢ e : τ τ ∈ {Int, Float}
-───────────────────────────────── [T-Neg]
-Γ; Φ ⊢ -e : τ
-
-Γ; Φ ⊢ e : Bool
-──────────────────── [T-Not]
-Γ; Φ ⊢ not e : Bool
-```
-
-#### Function Calls
-
-```
-Φ(f) = (τ₁,...,τₙ) → τᵣ
-Γ; Φ ⊢ e₁ : τ₁ ... Γ; Φ ⊢ eₙ : τₙ
-────────────────────────────────────── [T-Call]
-Γ; Φ ⊢ f(e₁,...,eₙ) : τᵣ
-```
-
-#### Arrays
-
-```
-Γ; Φ ⊢ e₁ : τ ... Γ; Φ ⊢ eₙ : τ
-────────────────────────────────── [T-Array]
-Γ; Φ ⊢ [e₁,...,eₙ] : [τ]
-
-Γ; Φ ⊢ e₁ : [τ] Γ; Φ ⊢ e₂ : Int
-──────────────────────────────────── [T-Index]
-Γ; Φ ⊢ e₁[e₂] : τ
-```
-
-#### Result Types
-
-```
-Γ; Φ ⊢ e : τ
-────────────────────────────── [T-Okay]
-Γ; Φ ⊢ Okay(e) : Result[τ, String]
-
-Γ; Φ ⊢ e : String
-────────────────────────────── [T-Oops]
-Γ; Φ ⊢ Oops(e) : Result[τ, String]
-
-Γ; Φ ⊢ e : Result[τ, τₑ]
-────────────────────────── [T-Unwrap]
-Γ; Φ ⊢ unwrap e : τ
-
-Γ; Φ ⊢ e : Result[τ, τₑ]
-────────────────────────── [T-IsOkay]
-Γ; Φ ⊢ isOkay(e) : Bool
-```
-
-#### Unit Measurement
-
-```
-Γ; Φ ⊢ e : τ τ ∈ {Int, Float}
-───────────────────────────────── [T-Measure]
-Γ; Φ ⊢ e measured in u : τ
-```
-
-### 2.2 Statement Typing
-
-```
-Γ; Φ ⊢ e : τ
-──────────────────────────────────── [T-VarDecl]
-Γ; Φ; τᵣ ⊢ remember x = e ⟹ Γ[x ↦ τ]
-
-Γ(x) = τ Γ; Φ ⊢ e : τ
-──────────────────────────────── [T-Assign]
-Γ; Φ; τᵣ ⊢ x = e ⟹ Γ
-
-Γ; Φ ⊢ e : τᵣ
-──────────────────────────── [T-Return]
-Γ; Φ; τᵣ ⊢ give back e ⟹ Γ
-
-Γ; Φ ⊢ e : Bool Γ; Φ; τᵣ ⊢ s₁* ⟹ Γ₁ Γ; Φ; τᵣ ⊢ s₂* ⟹ Γ₂
-──────────────────────────────────────────────────────────────── [T-If]
-Γ; Φ; τᵣ ⊢ when e {s₁*} otherwise {s₂*} ⟹ Γ
-
-Γ; Φ ⊢ e : Int Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
-──────────────────────────────────────── [T-Loop]
-Γ; Φ; τᵣ ⊢ repeat e times {s*} ⟹ Γ
-
-Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
-───────────────────────────────────────────────── [T-Attempt]
-Γ; Φ; τᵣ ⊢ attempt safely {s*} or reassure m ⟹ Γ
-
-Γ; Φ; τᵣ ⊢ s* ⟹ Γ'
-───────────────────────────────────────── [T-Consent]
-Γ; Φ; τᵣ ⊢ only if okay p {s*} ⟹ Γ
-```
-
-### 2.3 Function Typing
-
-```
-Γ₀ = [x₁ ↦ τ₁, ..., xₙ ↦ τₙ]
-Γ₀; Φ; τᵣ ⊢ body ⟹ Γ'
-────────────────────────────────────────────────────── [T-Func]
-Φ ⊢ to f(x₁:τ₁,...,xₙ:τₙ) → τᵣ { body } : (τ₁,...,τₙ) → τᵣ
-```
-
----
-
-## 3. Type Safety Theorems
-
-### 3.1 Canonical Forms Lemma
-
-**Lemma 3.1 (Canonical Forms):** If `⊢ v : τ` and v is a value, then:
-
-1. If τ = Int, then v = n for some n ∈ ℤ
-2. If τ = Float, then v = f for some f ∈ ℝ
-3. If τ = String, then v = s for some string s
-4. If τ = Bool, then v ∈ {true, false}
-5. If τ = Unit, then v = unit
-6. If τ = [τ'], then v = [v₁,...,vₙ] where ⊢ vᵢ : τ' for all i
-7. If τ = Result[τ₁, τ₂], then v = Okay(v') with ⊢ v' : τ₁ or v = Oops(s) with ⊢ s : τ₂
-8. If τ = (τ₁,...,τₙ) → τᵣ, then v is a closure
-
-**Proof:** By inspection of the typing rules and value forms. Each type has a unique set of value constructors. □
-
-### 3.2 Progress Theorem
-
-**Theorem 3.2 (Progress):** If `Γ; Φ ⊢ e : τ` and e is closed (contains no free variables not in Γ), then either:
-1. e is a value, or
-2. There exists e' such that `⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩`
-
-**Proof:** By structural induction on the typing derivation.
-
-**Case T-Int, T-Float, T-String, T-Bool, T-Unit:** e is already a value. ✓
-
-**Case T-Var:** `e = x` and `Γ(x) = τ`. Since e is closed, x ∈ dom(ρ), so `⟨x, ρ, Φ⟩ → ⟨ρ(x), ρ, Φ⟩` by [S-Var]. ✓
-
-**Case T-Add-Int:** `e = e₁ + e₂` with `Γ; Φ ⊢ e₁ : Int` and `Γ; Φ ⊢ e₂ : Int`.
-- By IH on e₁: either e₁ is a value or e₁ can step
- - If e₁ can step, then e can step by [S-Context] with E = □ + e₂
- - If e₁ is a value v₁, by IH on e₂: either e₂ is a value or e₂ can step
- - If e₂ can step, then e can step by [S-Context] with E = v₁ + □
- - If e₂ is a value v₂, by Canonical Forms, v₁ = n₁ and v₂ = n₂ for some integers
- - Then `⟨n₁ + n₂, ρ, Φ⟩ → ⟨n₁ + n₂, ρ, Φ⟩` by [S-BinOp] ✓
-
-**Case T-Call:** `e = f(e₁,...,eₙ)` with `Φ(f) = (τ₁,...,τₙ) → τᵣ` and `Γ; Φ ⊢ eᵢ : τᵢ`.
-- By IH, each eᵢ either is a value or can step
-- If any eᵢ can step, e can step by [S-Context]
-- If all eᵢ are values vᵢ, then by [S-Call], e steps to the function body with substituted parameters ✓
-
-**Case T-Index:** `e = e₁[e₂]` with `Γ; Φ ⊢ e₁ : [τ]` and `Γ; Φ ⊢ e₂ : Int`.
-- By IH on e₁ and e₂, both evaluate or step
-- If both are values, by Canonical Forms, e₁ = [v₀,...,vₖ] and e₂ = n
-- If 0 ≤ n ≤ k, then e steps to vₙ by [S-Index]
-- If n < 0 or n > k, evaluation gets stuck (runtime error)
-
-**Note:** Array bounds checking is a runtime check, not a static type check. The type system guarantees type safety, not memory safety in the bounds-checking sense. □
-
-### 3.3 Preservation Theorem
-
-**Theorem 3.3 (Preservation/Subject Reduction):** If `Γ; Φ ⊢ e : τ` and `⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩`, then `Γ; Φ ⊢ e' : τ`.
-
-**Proof:** By structural induction on the typing derivation, with case analysis on the reduction rule.
-
-**Case T-Var:** `e = x` with `Γ(x) = τ`.
-- The only applicable reduction is [S-Var]: `⟨x, ρ, Φ⟩ → ⟨ρ(x), ρ, Φ⟩`
-- We need `Γ; Φ ⊢ ρ(x) : τ`
-- This holds if the environment ρ is well-typed with respect to Γ (environment typing invariant) ✓
-
-**Case T-Add-Int:** `e = e₁ + e₂` with both typed as Int.
-- If `e = n₁ + n₂` (both values), reduction gives `n₁ + n₂ = n₃ ∈ ℤ`, and `Γ; Φ ⊢ n₃ : Int` by [T-Int] ✓
-- If e₁ or e₂ steps, by IH and [T-Add-Int], the result is still typed Int ✓
-
-**Case T-Call:** `e = f(v₁,...,vₙ)` where all arguments are values.
-- By [S-Call]: e reduces to body[x₁ := v₁, ..., xₙ := vₙ]
-- By [T-Func], the body is typed in environment `[x₁ ↦ τ₁, ..., xₙ ↦ τₙ]` with return type τᵣ
-- By Substitution Lemma (Lemma 3.4 below), substituting well-typed values preserves typing
-- Therefore `Γ; Φ ⊢ body[x₁ := v₁, ..., xₙ := vₙ] : τᵣ` ✓
-
-**Case T-Array:** `e = [e₁,...,eₙ]` with all eᵢ : τ.
-- If some eᵢ steps to e'ᵢ, by IH, `Γ; Φ ⊢ e'ᵢ : τ`
-- The array [e₁,...,e'ᵢ,...,eₙ] still has type [τ] by [T-Array] ✓
-
-**Case T-Index:** `e = [v₀,...,vₖ][n]` with array type [τ].
-- By [S-Index], e reduces to vₙ (assuming 0 ≤ n ≤ k)
-- Since [v₀,...,vₖ] : [τ], each vᵢ : τ by inversion
-- Therefore vₙ : τ ✓
-
-□
-
-### 3.4 Substitution Lemma
-
-**Lemma 3.4 (Substitution):** If `Γ, x:τ'; Φ ⊢ e : τ` and `Γ; Φ ⊢ v : τ'`, then `Γ; Φ ⊢ e[x := v] : τ`.
-
-**Proof:** By structural induction on the derivation of `Γ, x:τ'; Φ ⊢ e : τ`.
-
-**Case T-Var where e = x:** Then τ = τ' and e[x := v] = v. By assumption, `Γ; Φ ⊢ v : τ'` = `Γ; Φ ⊢ v : τ`. ✓
-
-**Case T-Var where e = y ≠ x:** Then e[x := v] = y and `(Γ, x:τ')(y) = τ = Γ(y)`. By [T-Var], `Γ; Φ ⊢ y : τ`. ✓
-
-**Case T-Add-Int:** `e = e₁ + e₂` with both subexpressions typed Int.
-- By IH, `Γ; Φ ⊢ e₁[x := v] : Int` and `Γ; Φ ⊢ e₂[x := v] : Int`
-- By [T-Add-Int], `Γ; Φ ⊢ (e₁ + e₂)[x := v] = e₁[x := v] + e₂[x := v] : Int` ✓
-
-Other cases follow similarly by IH and applying the appropriate typing rule. □
-
-### 3.5 Type Safety (Main Theorem)
-
-**Theorem 3.5 (Type Safety):** Well-typed programs don't go wrong.
-
-If `⊢ p : ok` and `⟨p, ∅, Φ⟩ →* ⟨e, ρ, Φ⟩`, then either:
-1. e is a value, or
-2. There exists e' such that `⟨e, ρ, Φ⟩ → ⟨e', ρ', Φ⟩`
-
-**Proof:** By induction on the number of reduction steps, using Progress and Preservation at each step. □
-
----
-
-## 4. Type Inference Properties
-
-### 4.1 Principal Types
-
-**Theorem 4.1 (Principal Types):** If e is typeable, then e has a principal type scheme σ such that all types of e are instances of σ.
-
-This follows from the Hindley-Milner nature of WokeLang's type system. See [hindley-milner.md](hindley-milner.md) for the type inference algorithm.
-
-### 4.2 Decidability
-
-**Theorem 4.2 (Decidability of Type Checking):** Type checking for WokeLang is decidable.
-
-**Proof:** The type inference algorithm (Algorithm W variant) terminates and produces a principal type or reports an error. □
-
-### 4.3 Completeness
-
-**Theorem 4.3 (Completeness of Type Inference):** If e has a type, the inference algorithm finds it.
-
----
-
-## 5. Subtyping Properties
-
-WokeLang has limited subtyping for numeric types:
-
-### 5.1 Subtyping Rules
-
-```
-─────────── [Sub-Refl]
-τ <: τ
-
-Int <: Float
-```
-
-### 5.2 Subsumption
-
-```
-Γ; Φ ⊢ e : τ τ <: τ'
-──────────────────────── [T-Sub]
-Γ; Φ ⊢ e : τ'
-```
-
-### 5.3 Subtyping Safety
-
-**Theorem 5.1 (Subtyping Safety):** If `Γ; Φ ⊢ e : τ` and `τ <: τ'`, then e can be safely used where τ' is expected.
-
-**Proof:** The only non-trivial subtyping is Int <: Float. Integer operations produce integers, and integers can be safely widened to floats in contexts expecting floats. □
-
----
-
-## 6. Error Cases and Runtime Checks
-
-The type system does **not** prevent these runtime errors:
-
-1. **Array bounds errors:** `[1,2,3][10]` is well-typed as Int but fails at runtime
-2. **Division by zero:** `x / 0` is well-typed but fails at runtime
-3. **Unwrap of Oops:** `unwrap Oops("error")` is well-typed but fails at runtime
-
-**TODO:** These could be addressed with:
-- Dependent types for array bounds
-- Refinement types for non-zero divisors
-- Linear types for Result handling (see verification/future-work.md)
-
----
-
-## 7. Implementation Correspondence
-
-The proofs correspond to the implementation in `src/typechecker/mod.rs`:
-
-| Theorem/Lemma | Implementation |
-|---------------|----------------|
-| Typing rules | `infer_expr()`, `check_statement()` |
-| Unification | `unify()` method |
-| Substitution | `apply_substitutions()` method |
-| Type environment | `TypeEnv` struct |
-| Error reporting | `TypeError` enum |
-
----
-
-## References
-
-1. Wright, A.K. and Felleisen, M. (1994). "A Syntactic Approach to Type Soundness"
-2. Pierce, B.C. (2002). "Types and Programming Languages"
-3. Harper, R. (2016). "Practical Foundations for Programming Languages"
-4. Milner, R. (1978). "A Theory of Type Polymorphism in Programming"
diff --git a/docs/proofs/verification/AUDIT.adoc b/docs/proofs/verification/AUDIT.adoc
new file mode 100644
index 0000000..3a53870
--- /dev/null
+++ b/docs/proofs/verification/AUDIT.adoc
@@ -0,0 +1,340 @@
+== WokeLang Proof Audit (Lean 4 + Coq)
+
+This document records a completeness/correspondence audit of the two
+formal developments — `+WokeLang.lean+` (Lean 4) and `+WokeLang.v+`
+(Coq) — answering the questions raised in
+link:../../../PROOF-NEEDS.md[`+PROOF-NEEDS.md+`]: _is the
+verified/sorry-free claim still true?_ and _do the proofs cover the full
+type system or only a subset?_ (The Lean sections come first; the Coq
+audit is its own section below.)
+
+=== Toolchain
+
+* *Prover:* Lean 4, pinned to *v4.30.0* (`+lean-toolchain+` in this
+directory).
+* *Build / check:* the proof file has *no external dependencies* (no
+Mathlib — only the Lean core prelude), so it is checked directly:
++
+[source,sh]
+----
+lean docs/proofs/verification/WokeLang.lean # exit 0, no output ⇒ verified
+----
+* *CI:* `+.github/workflows/lean-proofs.yml+` installs the pinned
+toolchain and runs the check on every push. See the headline finding
+below for why this gate was added.
+
+=== Headline finding — the proofs had bit-rotted (now fixed)
+
+The file’s doc-comment claimed _"`all 12 `+sorry+` eliminated …
+verified`"_. That claim was *true against an older Lean but had silently
+broken*: under Lean 4.30.0 the file did *not* compile (~100 errors). Two
+root causes:
+
+[arabic]
+. *`+deriving DecidableEq+` no longer applies* to `+Value+` and
+`+WokeType+`. `+Value+` contains `+Float+` (no `+DecidableEq+` in Lean 4
+— NaN), and both types nest `+List Self+`, which the `+DecidableEq+`
+deriving handler does not see through. Fixed by deriving only `+Repr+`;
+equality decisions that the proofs need (`+by_cases v₁ = v₂+`) work via
+Lean’s classical fallback with no instance required.
+. *`+induction h+` on `+HasType emptyTypeEnv …+`* fails because
+`+emptyTypeEnv+` is a _concrete_ (non-variable) index. Fixed by
+generalising the index (`+generalize hΓ : emptyTypeEnv = Γ at h+`) and
+threading the equation through the induction hypotheses.
+
+The decisive lesson: *no CI ever ran the prover* (workflows only covered
+the OCaml core and e2e), so the headline correctness claim was never
+enforced. The repair restores `+sorry+`-free compilation _and_ adds the
+missing CI gate.
+
+____
+The numeric "`12 `+sorry+``" figure in the file header is historical;
+the verified invariant going forward is simply _the CI `+lean+` check is
+green_.
+____
+
+=== Coverage — Lean model vs. the real language
+
+The Lean model formalises a *clean expression core* and is a *strict
+subset* of the surface language defined in `+core/ast.ml+` and
+implemented by the Rust type checker (`+src/typechecker/mod.rs+`).
+
+[width="100%",cols="34%,33%,33%",options="header",]
+|===
+|Area |Lean `+WokeLang.lean+` |Surface language (`+core/ast.ml+`,
+`+src/typechecker+`)
+|Literals |int, float, string, bool, unit |+ arrays, measured,
+`+thanks+`
+
+|Arithmetic |`+add+` only (int/float/string) |`+add sub mul div mod+` (+
+div/mod-by-zero), *mixed int/float promotion*
+
+|Comparison |`+eq+` (same-type), no ordering |`+eq ne lt gt le ge+`,
+structural `+eq+` across *any* types
+
+|Logical |`+and+` (both `+bool+`) |`+and or+` with *`+to_bool+`
+coercion* of any value
+
+|Result type |`+okay+`/`+oops+`/`+unwrap+`/`+error+`, `+tOkay…tUnwrap+`
+|present in *Rust* typechecker (`+Result(_, _)+`); *absent* from
+`+core/eval.ml+`
+
+|Unary |`+neg+` (int/float), `+not+` |+ measured propagation
+
+|Calls / arrays |`+call+` (no typing rule); *arrays typed + evaluated*
+(`+tArray+`/`+tArrayVal+`, `+sArrayStep+`/`+sArrayVal+`/`+sArrayErr+`)
+|builtins + user functions; arrays typed
+
+|Statements |*typing judgment* (`+StmtWellTyped+`, context-threading) +
+monotonicity/append metatheorems; execution/preservation not yet |full
+eval in `+core/eval.ml+`
+
+|Units of measure |*not modelled* |`+EMeasured+` / `+VMeasured+`,
+unit-match checking
+
+|Pattern matching, workers, custom types |*not modelled* |present
+
+|Consent |`+consent_monotonicity/preservation+` |matches *spec*
+`+axiomatic-semantics.md+` (consent Hoare logic)
+
+|Capabilities |data + `+capSubsumes+`/`+hasCapability+` (no theorems) |—
+|===
+
+==== What _is_ proven (and now machine-checked)
+
+`+canonical_forms_{int,float,string,bool,result}+`, *`+progress+`*,
+*`+preservation+`*, *`+type_safety+`* (multi-step), and
+`+consent_{monotonicity,preservation}+` — for the expression core above,
+including the Result/`+unwrap+`/`+error+` panic-propagation fragment.
+
+=== Correspondence map (re PROOF-NEEDS #2)
+
+PROOF-NEEDS #2 ("`prove evaluation semantics match the Lean spec`")
+rests on a *mismatch that must be acknowledged*: the three artefacts
+model _different_ languages.
+
+* *Lean type system / Result / progress+preservation* ⟷ the *Rust*
+`+src/typechecker+` (Hindley–Milner unification with `+Result+`,
+function types). This is the right correspondence target for the
+type-safety story.
+* *Lean `+consent_*+`* ⟷ the *spec* `+spec/axiomatic-semantics.md+`
+(consent Hoare triples). In correspondence. ✓
+* *`+core/eval.ml+`* is a _separate, older tree-walking interpreter_: it
+has *no Result type*, but adds units-of-measure, `+to_bool+` coercions,
+mixed int/float arithmetic, and structural cross-type `+eq+`. It is
+*not* the language the Lean `+Step+` relation models.
+
+Consequently, "`eval matches the Lean spec`" is *not* currently a
+well-posed single theorem — the evaluator and the spec diverge. The
+honest options are (a) treat `+WokeLang.lean+` as the *normative spec*
+and converge the implementations toward it, or (b) build a _second_ Lean
+model faithful to `+core/eval.ml+` (units + coercions + no Result) and
+prove properties there.
+
+=== Recommended next proof steps
+
+[arabic]
+. *Broaden the verified core toward the Rust type system* (each is a
+small, pattern-following extension to `+Step+`/`+HasType+` + the
+`+progress+`/ `+preservation+` cases, fully checkable):
+* integer `+sub+`/`+mul+` (total), then `+div+`/`+mod+` with a
+divide-by-zero `+error+` step (mirrors `+unwrap+`-of-`+oops+` panic
+propagation already proven);
+* ordering comparisons `+lt/gt/le/ge+` ⇒ `+bool+`;
+* `+or+` (mirror of `+and+`).
+. [line-through]#*Array typing* (`+tArray+`, an `+array+` congruence/▸
+value rule)# — *DONE (2026-06-18).* `+tArray+`/`+tArrayVal+` +
+`+sArrayStep+`/`+sArrayVal+`/ `+sArrayErr+`, with full
+`+progress+`/`+preservation+` coverage (see "`Extensions landed`"
+below). This brings Lean to parity with Coq on arrays.
+. [line-through]#Statement typing# — *DONE (2026-06-18):*
+`+StmtWellTyped+`/ `+StmtsWellTyped+` + monotonicity/append (see
+"`Statement typing landed`" below). *Next on statements: a dynamic
+story* — a statement execution relation + a store-typing _preservation_
+theorem. The prerequisite is generalising the expression
+`+preservation+`/`+type_safety+` to *open* terms (non-empty context + a
+store-typing agreement), since statement-embedded expressions reference
+declared variables (the current expression proofs assume the empty
+context, deriving a contradiction in the `+var+` case).
+. *Decide the eval-correspondence question* (a) vs (b) above with the
+maintainer before attempting PROOF-NEEDS #2.
+. *Compiler/VM track* (the file’s §8 TODO stubs: bytecode, compiler, VM
+semantics, compiler-correctness) remains open and is a larger effort.
+
+=== Echo-types design compatibility (checked 2026-06-14)
+
+Checked against echo-types `+main+` before extending WokeLang’s type
+system, so the extensions don’t box out a future echo/loss layer. The
+precedent is `+EchoEphapaxBridge+`: *Ephapax* (a linear-typed language)
+ports `+EchoLinear.agda+` + `+EchoResidue.agda+` into its prover as an
+*L3 layer* (`+formal/Echo.v+`, 584 lines Coq, zero axioms), preserving
+the headline theorems (`+weaken_collapses_distinction+`,
+`+affine_canonical+`, `+no_section_collapse_to_residue+`,
+`+degrade_mode_comp+`).
+
+* The echo/loss layer is a *`+Mode+`-indexed decoration*
+(`+linear ⊑ affine+`, `+weaken : LEcho linear → LEcho affine+`) sitting
+_on top of_ a base type system as a *separate module* — not a change to
+`+progress+`/`+preservation+`. So the Tier-1 base-operator extensions
+(`+or+`/`+sub+`/`+mul+`/…) are *orthogonal and compatible* by
+construction.
+* echo-types’ `+DecorationStructure+` is a *preorder* (`+≤-refl+`,
+`+≤-trans+`, `+≤-prop+`, `+join+`). WokeLang’s *capability subsumption
+is that shape* — the `+capSubsumes_refl+` / `+capSubsumes_trans+` lemmas
+are deliberately on-path to host echo decorations later.
+* *Integration blueprint* (not yet started): a Lean port of
+`+EchoLinear+` + `+EchoResidue+` as a `+WokeLang/Echo.lean+` L3 module,
+à la Ephapax’s Coq port, leaving the base type-safety proofs intact.
+
+=== Extensions landed (2026-06-14)
+
+* *Tier 1 (base operators)* — each with `+HasType+` + `+Step+` rules and
+full `+progress+`/`+preservation+` coverage:
+** logical: `+or+`;
+** integer arithmetic: `+sub+`, `+mul+`, `+div+`, `+mod+` — where
+`+div+`/`+mod+` panic on a zero divisor (step to `+error+`, reusing the
+proven `+unwrap+`-of-`+oops+` panic fragment);
+** ordering comparisons: `+lt+`, `+gt+`, `+le+`, `+ge+` (integer →
+`+bool+`, via `+decide+`).
+* *Tier 3 (capability):* `+capSubsumes+` is a preorder (`+_refl+`,
+`+_trans+`).
+* Still open in Tier 1: *float* arithmetic variants
+(`+sub+`/`+mul+`/`+div+` on `+float+`, mirroring `+add+` on float).
+
+=== Statement typing landed (2026-06-18) — both provers, in parity
+
+Statements went from _declared datatype with no judgments_ to a typed
+sub-language with machine-checked metatheory, in *both* Lean
+(`+WokeLang.lean+`) and Coq (`+WokeLang.v+`):
+
+* *Judgment* `+StmtWellTyped Γ s Γ'+` / `+StmtsWellTyped Γ ss Γ'+` — a
+context-threading typing relation over all nine statement forms
+(`+varDecl+`, `+assign+`, `+return+`, `+if+`, `+loop+`, `+attempt+`,
+`+consent+`, `+expr+`, `+complain+`), mutually inductive (blocks contain
+statements). `+varDecl+` extends the context; `+assign+` requires a
+prior declaration at the assigned type; compound statements are
+block-scoped (they return the incoming context). This is the
+statement-level analogue of the expression `+has_type+`/`+HasType+`.
+* *Metatheorems (all proved):*
+** `+ctxDomSub_{refl,trans,extend}+` — the context-domain preorder + the
+extension fact;
+** `+stmt_wellTyped_mono+` / `+stmts_wellTyped_mono+` — *context
+monotonicity*: a well-typed statement (or block) never undeclares a
+variable;
+** `+stmts_wellTyped_append+` — *sequencing composes*: typing one block
+then another from the resulting context types their concatenation;
+** `+stmts_wellTyped_example+` — an inhabitation smoke
+(`+let x = 0; x+`).
+* *Method note:* the single-statement metatheorems are non-recursive
+(blocks are scoped), which breaks the mutual dependency; the block
+versions then go by ordinary induction on the _list_ (sidestepping a
+mutual-induction scheme).
+* *Soundness:* Lean is `+sorry+`-free; in Coq `+Print Assumptions+`
+reports all four statement lemmas *"`Closed under the global context`"*
+— i.e. axiom-free (they do not touch the classical-reals axioms the
+float fragment needs).
+
+*Still open on statements:* the _dynamic_ story — an execution relation
++ store-typing preservation — which first needs open-term expression
+preservation (see "`Recommended next proof steps`" #3).
+
+=== Arrays landed (2026-06-18) — Lean now at parity with Coq
+
+The one array-shaped Tier-1 gap is closed on the Lean side, mirroring
+Coq’s `+T_Array+`/`+T_Lit_Array+`:
+
+* *Typing:* `+tArray+` (array expression, elementwise) and `+tArrayVal+`
+(fully-evaluated `+.vArray+` literal value), both with the `+∀ e ∈ es+`
+premise.
+* *Evaluation:* `+sArrayStep+` (reduce the left-most non-value element),
+`+sArrayVal+` (normalise `+.array (vs.map .lit)+` to
+`+.lit (.vArray vs)+`), and `+sArrayErr+` (propagate a panic out of an
+array, as the binop rules do). A fully-evaluated array is _not_ an
+`+IsValue+` — it always steps via `+sArrayVal+` to the array literal,
+which is the value. (This is cleaner than Coq, where a
+`+map ELit+`-array is simultaneously a value _and_ steppable, forcing
+extra array-equality step rules; in Lean, array equality reuses the
+generic `+.lit+`-equality rules after normalisation.)
+* *Proofs:* `+progress+` and `+preservation+` cover all three step
+rules, `+sorry+`-free and axiom-free under Lean 4.30.0. The helper
+`+array_split+` does the pure-list "`all-literals vs. prefix + first
+non-literal`" split (the analogue of Coq’s `+array_elements_progress+`).
+* *Method note:* Lean’s `+∀ e ∈ es+` premise yields a per-element
+induction hypothesis directly from `+induction+`, so the Lean
+`+progress+` needs *no well-founded recursion on an `+expr_size+`
+measure* — the device the Coq proof requires because Coq’s
+`+Forall+`-based scheme does not recurse into the nested `+has_type+`s.
+The two developments now prove the same array results by different
+means.
+
+=== Coq proofs (`+WokeLang.v+`) — audited 2026-06-14
+
+A parallel Coq formalization exists. It was given the same meticulous
+treatment as the Lean file.
+
+* *Toolchain:* Coq *8.18.0* (ubuntu-24.04 apt). Build / verify (the
+oracle): `+cd docs/proofs/verification && coqc WokeLang.v+` (exit 0 ⇒
+verified). CI gate: `+.github/workflows/coq-proofs.yml+` (pinned to
+ubuntu-24.04 — the file is version-sensitive).
+* *Rot found and fixed.* Like the Lean file, `+WokeLang.v+` did *not
+compile* (no CI ever ran the prover). The _only_ breakage:
+`+value_eq_dec+` used
+`+decide equality; … apply list_eq_dec; assumption+`, but the
+recursive IH for the nested `+list value+` is no longer in scope under
+8.18 → "`No such assumption`". Fixed with an explicit fixpoint
+(`+fix IH 1; …; apply list_eq_dec; exact IH+`). Everything else —
+including the large `+preservation+` proof — then compiled.
+* *Soundness (meticulous check).* No
+`+Admitted+`/`+admit+`/`+Axiom+`/`+Conjecture+`. `+Print Assumptions+`
+on `+progress+`/`+preservation+`/`+type_safety+` shows they depend
+*only* on `+ClassicalDedekindReals.sig_forall_dec+` +
+`+functional_extensionality+` — both pulled in _unavoidably_ by
+modelling floats as real numbers (`+R+`), exactly as the file header
+claims ("`no new axioms beyond those implicit in `+Coq.Reals+``").
+Consistent, standard, honest.
+* *Coverage vs. the Lean file.* Complementary, not identical:
+** Arrays are *now at parity* (Lean caught up 2026-06-18): both have
+`+T_Array+`/`+T_Lit_Array+` (Coq) ⟷ `+tArray+`/`+tArrayVal+` (Lean) and
+array stepping. The proofs differ in method: Coq’s `+progress+` uses
+*well-founded induction on `+expr_size+`* to get an IH for array
+elements (its `+Forall+`-based induction scheme does not recurse into
+the nested `+has_type+`s); Lean phrases the premise as `+∀ e ∈ es+`,
+which yields the per-element IH directly, so no size measure is needed.
+Coq additionally treats a `+map ELit+`-array as a value (needing extra
+array-equality step rules); Lean normalises arrays to a `+.vArray+`
+literal first and reuses generic `+.lit+`-equality.
+** Coq models floats as `+ℝ+` ⇒ `+value_eq_dec+` is fully decidable
+(`+Req_EM_T+`), at the cost of the classical-reals axioms above. (Lean
+models `+Float+` as opaque IEEE and decides equality classically via
+`+by_cases+`.)
+** Coq is now *at parity on integer binops* (landed 2026-06-15): on top
+of `+add+`/`+eq+`/`+and+` it gains `+or+`, `+sub+`, `+mul+`,
+`+div+`/`+mod+` (which panic to `+VOops+` on a zero divisor, mirroring
+the proven unwrap-of-oops fragment) and the comparisons
+`+lt+`/`+gt+`/`+le+`/`+ge+` (`+Z+` → `+bool+`) — each with a
+`+has_type+` rule, a `+step+` rule, and full
+`+progress+`/`+preservation+` coverage, axiom-free. Float arithmetic
+variants remain unmodelled on both sides, and `+BNeq+` is a symmetric
+gap (neither Lean nor Coq has it).
+* *`+cap_subsumes+` bug fixed.* Its catch-all was `+TODO: false+`, so
+the relation was *not even reflexive*
+(`+cap_subsumes CapProcess CapProcess = false+`). Fixed to fall back to
+decidable equality (`+capability_eq_dec+`), and `+cap_subsumes_refl+` is
+now proven (axiom-free). `+cap_subsumes_trans+` is a documented
+follow-up (the relation is transitive; a robust Coq proof needs explicit
+per-kind case analysis, not the brittle 6×6×6 automation).
+* *Quality follow-up (flagged, not blocking).* The `+preservation+`
+proof is a large brute-force `+try solve [...]+` pile ending in a
+literal _"`Nuclear option`"_ — it compiles and is axiom-honest, but is
+fragile and unreviewable. A clean per-case rewrite (in the style of the
+Lean `+preservation+`) is worth doing — the binop-parity work
+(2026-06-15) extended its `+first [...]+` reconstruction block and added
+an early literal-result closer rather than rewriting it. (That cascade
+also scales badly: the new ops had to be closed early and
+deterministically to avoid a multi-minute typecheck.)
+
+=== Status
+
+* Repair to `+sorry+`-free under Lean 4.30.0: see CI / `+lean+` check.
+* Coverage: *subset* of the surface language, as tabulated above — _not_
+a full-language proof, and honestly so.
diff --git a/docs/proofs/verification/AUDIT.md b/docs/proofs/verification/AUDIT.md
deleted file mode 100644
index 481206f..0000000
--- a/docs/proofs/verification/AUDIT.md
+++ /dev/null
@@ -1,290 +0,0 @@
-
-# WokeLang Proof Audit (Lean 4 + Coq)
-
-This document records a completeness/correspondence audit of the two formal
-developments — `WokeLang.lean` (Lean 4) and `WokeLang.v` (Coq) — answering the
-questions raised in [`PROOF-NEEDS.md`](../../../PROOF-NEEDS.md): *is the
-verified/sorry-free claim still true?* and *do the proofs cover the full type
-system or only a subset?* (The Lean sections come first; the Coq audit is its
-own section below.)
-
-## Toolchain
-
-- **Prover:** Lean 4, pinned to **v4.30.0** (`lean-toolchain` in this
- directory).
-- **Build / check:** the proof file has **no external dependencies**
- (no Mathlib — only the Lean core prelude), so it is checked directly:
-
- ```sh
- lean docs/proofs/verification/WokeLang.lean # exit 0, no output ⇒ verified
- ```
-
-- **CI:** `.github/workflows/lean-proofs.yml` installs the pinned toolchain
- and runs the check on every push. See the headline finding below for why
- this gate was added.
-
-## Headline finding — the proofs had bit-rotted (now fixed)
-
-The file's doc-comment claimed *"all 12 `sorry` eliminated … verified"*. That
-claim was **true against an older Lean but had silently broken**: under Lean
-4.30.0 the file did **not** compile (~100 errors). Two root causes:
-
-1. **`deriving DecidableEq` no longer applies** to `Value` and `WokeType`.
- `Value` contains `Float` (no `DecidableEq` in Lean 4 — NaN), and both types
- nest `List Self`, which the `DecidableEq` deriving handler does not see
- through. Fixed by deriving only `Repr`; equality decisions that the proofs
- need (`by_cases v₁ = v₂`) work via Lean's classical fallback with no
- instance required.
-2. **`induction h` on `HasType emptyTypeEnv …`** fails because `emptyTypeEnv`
- is a *concrete* (non-variable) index. Fixed by generalising the index
- (`generalize hΓ : emptyTypeEnv = Γ at h`) and threading the equation
- through the induction hypotheses.
-
-The decisive lesson: **no CI ever ran the prover** (workflows only covered the
-OCaml core and e2e), so the headline correctness claim was never enforced.
-The repair restores `sorry`-free compilation *and* adds the missing CI gate.
-
-> The numeric "12 `sorry`" figure in the file header is historical; the
-> verified invariant going forward is simply *the CI `lean` check is green*.
-
-## Coverage — Lean model vs. the real language
-
-The Lean model formalises a **clean expression core** and is a **strict
-subset** of the surface language defined in `core/ast.ml` and implemented by
-the Rust type checker (`src/typechecker/mod.rs`).
-
-| Area | Lean `WokeLang.lean` | Surface language (`core/ast.ml`, `src/typechecker`) |
-|---|---|---|
-| Literals | int, float, string, bool, unit | + arrays, measured, `thanks` |
-| Arithmetic | `add` only (int/float/string) | `add sub mul div mod` (+ div/mod-by-zero), **mixed int/float promotion** |
-| Comparison | `eq` (same-type), no ordering | `eq ne lt gt le ge`, structural `eq` across **any** types |
-| Logical | `and` (both `bool`) | `and or` with **`to_bool` coercion** of any value |
-| Result type | `okay`/`oops`/`unwrap`/`error`, `tOkay…tUnwrap` | present in **Rust** typechecker (`Result(_, _)`); **absent** from `core/eval.ml` |
-| Unary | `neg` (int/float), `not` | + measured propagation |
-| Calls / arrays | `call` (no typing rule); **arrays typed + evaluated** (`tArray`/`tArrayVal`, `sArrayStep`/`sArrayVal`/`sArrayErr`) | builtins + user functions; arrays typed |
-| Statements | **typing judgment** (`StmtWellTyped`, context-threading) + monotonicity/append metatheorems; execution/preservation not yet | full eval in `core/eval.ml` |
-| Units of measure | **not modelled** | `EMeasured` / `VMeasured`, unit-match checking |
-| Pattern matching, workers, custom types | **not modelled** | present |
-| Consent | `consent_monotonicity/preservation` | matches **spec** `axiomatic-semantics.md` (consent Hoare logic) |
-| Capabilities | data + `capSubsumes`/`hasCapability` (no theorems) | — |
-
-### What *is* proven (and now machine-checked)
-`canonical_forms_{int,float,string,bool,result}`, **`progress`**,
-**`preservation`**, **`type_safety`** (multi-step), and
-`consent_{monotonicity,preservation}` — for the expression core above,
-including the Result/`unwrap`/`error` panic-propagation fragment.
-
-## Correspondence map (re PROOF-NEEDS #2)
-
-PROOF-NEEDS #2 ("prove evaluation semantics match the Lean spec") rests on a
-**mismatch that must be acknowledged**: the three artefacts model *different*
-languages.
-
-- **Lean type system / Result / progress+preservation** ⟷ the **Rust**
- `src/typechecker` (Hindley–Milner unification with `Result`, function
- types). This is the right correspondence target for the type-safety story.
-- **Lean `consent_*`** ⟷ the **spec** `spec/axiomatic-semantics.md` (consent
- Hoare triples). In correspondence. ✓
-- **`core/eval.ml`** is a *separate, older tree-walking interpreter*: it has
- **no Result type**, but adds units-of-measure, `to_bool` coercions, mixed
- int/float arithmetic, and structural cross-type `eq`. It is **not** the
- language the Lean `Step` relation models.
-
-Consequently, "eval matches the Lean spec" is **not** currently a
-well-posed single theorem — the evaluator and the spec diverge. The honest
-options are (a) treat `WokeLang.lean` as the **normative spec** and converge
-the implementations toward it, or (b) build a *second* Lean model faithful to
-`core/eval.ml` (units + coercions + no Result) and prove properties there.
-
-## Recommended next proof steps
-
-1. **Broaden the verified core toward the Rust type system** (each is a small,
- pattern-following extension to `Step`/`HasType` + the `progress`/
- `preservation` cases, fully checkable):
- - integer `sub`/`mul` (total), then `div`/`mod` with a divide-by-zero
- `error` step (mirrors `unwrap`-of-`oops` panic propagation already
- proven);
- - ordering comparisons `lt/gt/le/ge` ⇒ `bool`;
- - `or` (mirror of `and`).
-2. ~~**Array typing** (`tArray`, an `array` congruence/▸ value rule)~~ —
- **DONE (2026-06-18).** `tArray`/`tArrayVal` + `sArrayStep`/`sArrayVal`/
- `sArrayErr`, with full `progress`/`preservation` coverage (see
- "Extensions landed" below). This brings Lean to parity with Coq on arrays.
-3. ~~Statement typing~~ — **DONE (2026-06-18):** `StmtWellTyped`/
- `StmtsWellTyped` + monotonicity/append (see "Statement typing landed"
- below). **Next on statements: a dynamic story** — a statement execution
- relation + a store-typing *preservation* theorem. The prerequisite is
- generalising the expression `preservation`/`type_safety` to **open** terms
- (non-empty context + a store-typing agreement), since statement-embedded
- expressions reference declared variables (the current expression proofs
- assume the empty context, deriving a contradiction in the `var` case).
-4. **Decide the eval-correspondence question** (a) vs (b) above with the
- maintainer before attempting PROOF-NEEDS #2.
-5. **Compiler/VM track** (the file's §8 TODO stubs: bytecode, compiler,
- VM semantics, compiler-correctness) remains open and is a larger effort.
-
-## Echo-types design compatibility (checked 2026-06-14)
-
-Checked against echo-types `main` before extending WokeLang's type system, so
-the extensions don't box out a future echo/loss layer. The precedent is
-`EchoEphapaxBridge`: **Ephapax** (a linear-typed language) ports
-`EchoLinear.agda` + `EchoResidue.agda` into its prover as an **L3 layer**
-(`formal/Echo.v`, 584 lines Coq, zero axioms), preserving the headline
-theorems (`weaken_collapses_distinction`, `affine_canonical`,
-`no_section_collapse_to_residue`, `degrade_mode_comp`).
-
-- The echo/loss layer is a **`Mode`-indexed decoration** (`linear ⊑ affine`,
- `weaken : LEcho linear → LEcho affine`) sitting *on top of* a base type
- system as a **separate module** — not a change to `progress`/`preservation`.
- So the Tier-1 base-operator extensions (`or`/`sub`/`mul`/…) are **orthogonal
- and compatible** by construction.
-- echo-types' `DecorationStructure` is a **preorder** (`≤-refl`, `≤-trans`,
- `≤-prop`, `join`). WokeLang's **capability subsumption is that shape** — the
- `capSubsumes_refl` / `capSubsumes_trans` lemmas are deliberately on-path to
- host echo decorations later.
-- **Integration blueprint** (not yet started): a Lean port of `EchoLinear` +
- `EchoResidue` as a `WokeLang/Echo.lean` L3 module, à la Ephapax's Coq port,
- leaving the base type-safety proofs intact.
-
-## Extensions landed (2026-06-14)
-
-- **Tier 1 (base operators)** — each with `HasType` + `Step` rules and full
- `progress`/`preservation` coverage:
- - logical: `or`;
- - integer arithmetic: `sub`, `mul`, `div`, `mod` — where `div`/`mod` panic on
- a zero divisor (step to `error`, reusing the proven `unwrap`-of-`oops`
- panic fragment);
- - ordering comparisons: `lt`, `gt`, `le`, `ge` (integer → `bool`, via
- `decide`).
-- **Tier 3 (capability):** `capSubsumes` is a preorder (`_refl`, `_trans`).
-- Still open in Tier 1: **float** arithmetic variants (`sub`/`mul`/`div` on
- `float`, mirroring `add` on float).
-
-## Statement typing landed (2026-06-18) — both provers, in parity
-
-Statements went from *declared datatype with no judgments* to a typed
-sub-language with machine-checked metatheory, in **both** Lean (`WokeLang.lean`)
-and Coq (`WokeLang.v`):
-
-- **Judgment** `StmtWellTyped Γ s Γ'` / `StmtsWellTyped Γ ss Γ'` — a
- context-threading typing relation over all nine statement forms (`varDecl`,
- `assign`, `return`, `if`, `loop`, `attempt`, `consent`, `expr`, `complain`),
- mutually inductive (blocks contain statements). `varDecl` extends the
- context; `assign` requires a prior declaration at the assigned type;
- compound statements are block-scoped (they return the incoming context).
- This is the statement-level analogue of the expression `has_type`/`HasType`.
-- **Metatheorems (all proved):**
- - `ctxDomSub_{refl,trans,extend}` — the context-domain preorder + the
- extension fact;
- - `stmt_wellTyped_mono` / `stmts_wellTyped_mono` — **context monotonicity**:
- a well-typed statement (or block) never undeclares a variable;
- - `stmts_wellTyped_append` — **sequencing composes**: typing one block then
- another from the resulting context types their concatenation;
- - `stmts_wellTyped_example` — an inhabitation smoke (`let x = 0; x`).
-- **Method note:** the single-statement metatheorems are non-recursive (blocks
- are scoped), which breaks the mutual dependency; the block versions then go
- by ordinary induction on the *list* (sidestepping a mutual-induction scheme).
-- **Soundness:** Lean is `sorry`-free; in Coq `Print Assumptions` reports all
- four statement lemmas **"Closed under the global context"** — i.e. axiom-free
- (they do not touch the classical-reals axioms the float fragment needs).
-
-**Still open on statements:** the *dynamic* story — an execution relation +
-store-typing preservation — which first needs open-term expression
-preservation (see "Recommended next proof steps" #3).
-
-## Arrays landed (2026-06-18) — Lean now at parity with Coq
-
-The one array-shaped Tier-1 gap is closed on the Lean side, mirroring Coq's
-`T_Array`/`T_Lit_Array`:
-
-- **Typing:** `tArray` (array expression, elementwise) and `tArrayVal`
- (fully-evaluated `.vArray` literal value), both with the `∀ e ∈ es` premise.
-- **Evaluation:** `sArrayStep` (reduce the left-most non-value element),
- `sArrayVal` (normalise `.array (vs.map .lit)` to `.lit (.vArray vs)`), and
- `sArrayErr` (propagate a panic out of an array, as the binop rules do). A
- fully-evaluated array is *not* an `IsValue` — it always steps via `sArrayVal`
- to the array literal, which is the value. (This is cleaner than Coq, where a
- `map ELit`-array is simultaneously a value *and* steppable, forcing extra
- array-equality step rules; in Lean, array equality reuses the generic
- `.lit`-equality rules after normalisation.)
-- **Proofs:** `progress` and `preservation` cover all three step rules,
- `sorry`-free and axiom-free under Lean 4.30.0. The helper `array_split`
- does the pure-list "all-literals vs. prefix + first non-literal" split
- (the analogue of Coq's `array_elements_progress`).
-- **Method note:** Lean's `∀ e ∈ es` premise yields a per-element induction
- hypothesis directly from `induction`, so the Lean `progress` needs **no
- well-founded recursion on an `expr_size` measure** — the device the Coq
- proof requires because Coq's `Forall`-based scheme does not recurse into the
- nested `has_type`s. The two developments now prove the same array results by
- different means.
-
-## Coq proofs (`WokeLang.v`) — audited 2026-06-14
-
-A parallel Coq formalization exists. It was given the same meticulous
-treatment as the Lean file.
-
-- **Toolchain:** Coq **8.18.0** (ubuntu-24.04 apt). Build / verify (the oracle):
- `cd docs/proofs/verification && coqc WokeLang.v` (exit 0 ⇒ verified). CI gate:
- `.github/workflows/coq-proofs.yml` (pinned to ubuntu-24.04 — the file is
- version-sensitive).
-
-- **Rot found and fixed.** Like the Lean file, `WokeLang.v` did **not compile**
- (no CI ever ran the prover). The *only* breakage: `value_eq_dec` used `decide
- equality; … apply list_eq_dec; assumption`, but the recursive IH for the
- nested `list value` is no longer in scope under 8.18 → "No such assumption".
- Fixed with an explicit fixpoint (`fix IH 1; …; apply list_eq_dec; exact IH`).
- Everything else — including the large `preservation` proof — then compiled.
-
-- **Soundness (meticulous check).** No `Admitted`/`admit`/`Axiom`/`Conjecture`.
- `Print Assumptions` on `progress`/`preservation`/`type_safety` shows they
- depend **only** on `ClassicalDedekindReals.sig_forall_dec` +
- `functional_extensionality` — both pulled in *unavoidably* by modelling
- floats as real numbers (`R`), exactly as the file header claims ("no new
- axioms beyond those implicit in `Coq.Reals`"). Consistent, standard, honest.
-
-- **Coverage vs. the Lean file.** Complementary, not identical:
- - Arrays are **now at parity** (Lean caught up 2026-06-18): both have
- `T_Array`/`T_Lit_Array` (Coq) ⟷ `tArray`/`tArrayVal` (Lean) and array
- stepping. The proofs differ in method: Coq's `progress` uses **well-founded
- induction on `expr_size`** to get an IH for array elements (its
- `Forall`-based induction scheme does not recurse into the nested
- `has_type`s); Lean phrases the premise as `∀ e ∈ es`, which yields the
- per-element IH directly, so no size measure is needed. Coq additionally
- treats a `map ELit`-array as a value (needing extra array-equality step
- rules); Lean normalises arrays to a `.vArray` literal first and reuses
- generic `.lit`-equality.
- - Coq models floats as `ℝ` ⇒ `value_eq_dec` is fully decidable (`Req_EM_T`),
- at the cost of the classical-reals axioms above. (Lean models `Float` as
- opaque IEEE and decides equality classically via `by_cases`.)
- - Coq is now **at parity on integer binops** (landed 2026-06-15): on top of
- `add`/`eq`/`and` it gains `or`, `sub`, `mul`, `div`/`mod` (which panic to
- `VOops` on a zero divisor, mirroring the proven unwrap-of-oops fragment) and
- the comparisons `lt`/`gt`/`le`/`ge` (`Z` → `bool`) — each with a `has_type`
- rule, a `step` rule, and full `progress`/`preservation` coverage, axiom-free.
- Float arithmetic variants remain unmodelled on both sides, and `BNeq` is a
- symmetric gap (neither Lean nor Coq has it).
-
-- **`cap_subsumes` bug fixed.** Its catch-all was `TODO: false`, so the relation
- was **not even reflexive** (`cap_subsumes CapProcess CapProcess = false`).
- Fixed to fall back to decidable equality (`capability_eq_dec`), and
- `cap_subsumes_refl` is now proven (axiom-free). `cap_subsumes_trans` is a
- documented follow-up (the relation is transitive; a robust Coq proof needs
- explicit per-kind case analysis, not the brittle 6×6×6 automation).
-
-- **Quality follow-up (flagged, not blocking).** The `preservation` proof is a
- large brute-force `try solve [...]` pile ending in a literal *"Nuclear
- option"* — it compiles and is axiom-honest, but is fragile and unreviewable.
- A clean per-case rewrite (in the style of the Lean `preservation`) is worth
- doing — the binop-parity work (2026-06-15) extended its `first [...]`
- reconstruction block and added an early literal-result closer rather than
- rewriting it. (That cascade also scales badly: the new ops had to be closed
- early and deterministically to avoid a multi-minute typecheck.)
-
-## Status
-
-- Repair to `sorry`-free under Lean 4.30.0: see CI / `lean` check.
-- Coverage: **subset** of the surface language, as tabulated above — *not* a
- full-language proof, and honestly so.
diff --git a/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.adoc b/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.adoc
new file mode 100644
index 0000000..9cccd67
--- /dev/null
+++ b/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.adoc
@@ -0,0 +1,338 @@
+== WokeLang Grammar — Proof-Obligation Inventory & Audit
+
+This document is the *complete inventory* of every formal claim made
+_about the grammar_ in
+link:../formal-semantics/grammar-proofs.md[`+grammar-proofs.md+`], with,
+for each: whether it is *faithfully machine-checkable* in the repo’s
+prover setup (Lean 4.30.0 / Coq 8.18.0, single-file, no Mathlib,
+offline), its *priority*, and its *status*.
+
+It answers the question the user posed: _which grammar proofs are
+needed, which are wanted, and which are actually done (run in a prover)
+vs. merely asserted in prose._
+
+=== Ground truth established first
+
+* *Canonical grammar:* `+grammar/wokelang.ebnf+`, _verified against the
+live implementation_ (`+src/lexer/token.rs+` identifier rule
+`+[a-zA-Z][a-zA-Z0-9_]*+`; `+src/parser/mod.rs+` support for
+`+while+`/`+break+`/`+continue+`, lambdas, record literals, field
+access, function types). The older `+spec/grammar.ebnf+` was a *stale
+subset* falsely claiming to supersede it; it is now a generated
+synchronized copy guarded by `+scripts/check-grammar-sync.sh+`.
+* *Provers actually installed and run here:* Coq *8.18.0* (apt) and Lean
+*4.30.0* (pinned by `+lean-toolchain+`, installed from the GitHub
+release — the `+*.lean-lang.org+` resolver hosts are blocked by egress
+policy, so the tarball is fetched directly from `+github.com+`, exactly
+as `+lean-proofs.yml+` already does in CI). Baseline check before any
+new work: the *existing* `+WokeLang.lean+` and `+WokeLang.v+` both
+compile clean (exit 0), sorry/admit-free.
+* *Before this work there were ZERO machine-checked grammar proofs.*
+Every claim in `+grammar-proofs.md+` was English prose. The
+machine-checked `+WokeLang.{lean,v}+` cover the _type system /
+semantics_ (on the AST), not the grammar/parser.
+
+=== The parser being modelled (so the proofs are faithful, not invented)
+
+`+src/parser/mod.rs+` is a *precedence-climbing (Pratt)
+recursive-descent* parser. Precedence ladder (higher binds tighter):
+
+[width="99%",cols="12%,11%,11%,11%,11%,11%,11%,11%,11%",options="header",]
+|===
+|Level |1 |2 |3 |4 |5 |6 |7 |8
+| |`+or+` |`+and+` |`+== !=+` |`+< > <= >=+` |`++ -+` |`+* / %+` |unary
+`+- not+` |postfix `+. () []+`
+|===
+
+Infix recursion uses *strict `+<+`* on the operator’s own level ⇒ all
+binary operators are *left-associative*. This is exactly the EBNF
+repetition ladder (`+logical_or = logical_and , { "or" , logical_and }+`
+…). The Lean/Coq models reproduce this structure so
+soundness/completeness/precedence are about _this_ parser, not a toy.
+
+=== Inventory
+
+Legend — *Faithful?*: can it be mechanized _as the prose states it_ in
+this setup? *Status*: `+MACHINE-CHECKED+` (compiles in a prover here) ·
+`+PROSE-ONLY+` (was, and remains, an informal argument) · `+FLAGGED+`
+(honestly out of faithful reach here, with reason).
+
+[width="99%",cols="20%,16%,16%,16%,16%,16%",options="header",]
+|===
+|# |Prose claim (grammar-proofs.md) |Faithful here? |Priority
+|Mechanization |Status
+|T2.1 |§2.1 No left recursion |✅ yes (whole grammar) |*P2* |Grammar as
+data; rank-decreasing `+Reach+` ⇒ `+¬ Reach a a+` over *all* productions
+|MACHINE-CHECKED (*+ found a real discrepancy:* the guard pattern IS
+left-recursive — see below)
+
+|T2.2 |§2.2 Unambiguity |✅ for the core (undecidable in general) |*P1*
+|Determinism of the verified parser ⇒ unique parse:
+`+Derives ts e₁ → Derives ts e₂ → e₁=e₂+` for the expression core
+|MACHINE-CHECKED (core)
+
+|T2.3 |§2.3 LL(2) |◑ partial |*P4* |The one 2-token decision (`+ident+`
+vs `+ident(+`) witnessed; determinism of the core parser. Full LL(2)
+table for all 94 productions is not built |MACHINE-CHECKED (witness)
+
+|T3.1 |§3.1 Parser soundness |✅ for the core |*P1*
+|`+parse ts = some (e, rest) → Derives (consumed) e+` |MACHINE-CHECKED
+(core)
+
+|T3.2 |§3.2 Parser completeness |✅ for the core |*P1*
+|`+Derives ts e → parse ts = some (e, [])+` |MACHINE-CHECKED (core)
+
+|T3.3 |§3.3 Parser termination |✅ |*P1* |Totality of `+parse+`
+(Lean/Coq accept the definition ⇒ it terminates on every input) +
+explicit fuel/measure |MACHINE-CHECKED
+
+|T4.1 |§4.2 Maximal munch (longest match) |✅ for the keyword/identifier
+fragment |*P3* |`+classify+` longest-prefix lemma; `+"remembering"+` ↦
+identifier not `+remember+`+`+ing+` |MACHINE-CHECKED (fragment)
+
+|T4.2 |§4.3 Keyword priority |✅ |*P3*
+|`+classify "remember" = Remember+` and a general "`a string equal to a
+keyword classifies as that keyword`" lemma |MACHINE-CHECKED
+
+|T6.1 |§6.2 Pratt precedence correctness |✅ |*P1* |General precedence
+lemma + concrete `+1+2*3 ↦ 1+(2*3)+`, `+1*2+3 ↦ (1*2)+3+`
+|MACHINE-CHECKED
+
+|T6.3 |§6.3 Left-associativity |✅ |*P1* |`+a-b-c ↦ (a-b)-c+` from the
+strict-`+<+` model + general statement |MACHINE-CHECKED
+
+|T1.1 |§1.1 CFG membership |✅ |*P4* |By construction (the grammar
+relation is a CFG) |MACHINE-CHECKED
+
+|T1.2 |§1.1 LL(1) = ✗ |✅ |*P4* |Exhibit the FIRST/FIRST conflict
+(`+primary → identifier+` vs `+identifier "(" …+`) — a 1-lookahead
+non-determinism witness |MACHINE-CHECKED
+
+|T7.3a |§7.3 CFL closed under ∪, ·, * |✅ done from scratch |*P5→done*
+|`+WokeGrammarCFL.lean+`: CFG derivation relation + reusable embedding
+lemma + union/concat/star grammar constructions, `+propext+`-only
+|MACHINE-CHECKED
+
+|T7.1 |§7.1 Not regular (pumping lemma) |✅ done from scratch |*P6→done*
+|`+WokeGrammarRegular.lean+`: bespoke finite pigeonhole + `+Fin k+` DFA
++ fooling-set on `+aⁿbⁿ+` (≅ `+(ⁿ)ⁿ+`), Mathlib-free |MACHINE-CHECKED
+
+|T7.0 |CFL pumping lemma (Mathlib-gap) |✅ done from scratch |*Ext*
+|`+WokeGrammarPumping.lean+`: `+cfl_pumping+` —
+`+descend+`/`+ht_descend+`/`+nodeNT_add+` spine navigation +
+`+Ctx.comp+` + pigeonhole ⇒ `+z = uvwxy+`, `+1≤|vx|+`,
+`+|vwx|≤2^(card+1)+`, `+uvⁱwxⁱy ∈ L+`; classical kernel constants only
+|MACHINE-CHECKED
+
+|T7.0b |`+aⁿbⁿcⁿ ∉ CFL+` (canonical non-CFL) |✅ done from scratch
+|*Ext* |`+WokeGrammarPumping.lean+`: `+anbncn_not_cfl+` via
+`+cfl_pumping+` (pump `+i=0+` ⇒ equal counts ⇒ window spans `+a+`…`+c+`
+⇒ `+|vwx|>p+`); positional core `+prefix_pure+`/`+abc_window+`;
+classical kernel constants only |MACHINE-CHECKED
+
+|T7.3b |§7.3 CFL *not* closed under ∩ |✅ done from scratch |*P6→done*
+|`+WokeGrammarPumping.lean+`: `+cfl_not_closed_inter+` — witnesses
+`+L₁={aⁱbⁱcʲ}+`, `+L₂={aᵐbⁿcⁿ}+` are CFL (explicit BNF grammars
+`+R1+`,`+R2+` + soundness via tree inversion + completeness via tree
+building), `+L₁∩L₂={aⁿbⁿcⁿ}+` not CFL (T7.0b) |MACHINE-CHECKED
+|===
+
+=== Priority order (execution)
+
+[arabic]
+. *P1 — expression-core verified parser* (`+WokeGrammar.lean/.v+`):
+discharges T3.1, T3.2, T3.3, T2.2(core), T6.1, T6.3, and feeds T2.3.
+Biggest and most load-bearing — the precedence/associativity/soundness
+story.
+. *P2 — whole-grammar no-left-recursion* (T2.1): the only claim that is
+honestly provable for the _entire_ 94-production grammar, not just a
+core.
+. *P3 — lexer maximal-munch + keyword-priority* (T4.1, T4.2).
+. *P4 — classification* (T1.1 CFG, T1.2 LL(1)✗, T2.3 LL(2) witness).
+. *P5 — CFL positive closure* (T7.3a).
+. *P6 — non-regularity + non-closure* (T7.1, T7.0/T7.0b, T7.3b):
+originally flagged, now all machine-checked from scratch (DFA
+fooling-set; CFL pumping lemma; `+aⁿbⁿcⁿ ∉ CFL+`; ∩ non-closure with
+explicit witness grammars).
+
+Then *mirror P1–P5 to Coq* (the repo keeps Lean/Coq in lockstep) and
+*gate both in CI*.
+
+=== What is deliberately NOT claimed
+
+* *Completeness against the _Rust_ parser byte-for-byte* is _not_
+asserted: the proofs are against a Lean/Coq model that faithfully
+reproduces the parser’s precedence-climbing structure. Bridging
+model↔Rust would need a verified extraction or a Rust semantics, which
+neither prover provides here. The model is justified by the structural
+correspondence documented above, not by extraction.
+* *Full-CFG unambiguity* (T2.2 for the _entire_ grammar) is undecidable;
+only the core is proven unambiguous (via parser determinism).
+* The *non-regularity / non-closure* results (T7.1, T7.3b) were
+initially flagged; they are now fully machine-checked from scratch (see
+P6) — never faked.
+
+=== Landed — P1 (`+WokeGrammar.lean+`, Lean 4.30.0)
+
+Machine-checked and CI-gated (`+.github/workflows/lean-proofs.yml+`).
+Compiles clean (`+lean WokeGrammar.lean+`, exit 0),
+*`+sorry+`/`+admit+`/`+native_decide+`-free*. `+#print axioms+` on the
+headline theorems shows dependence only on `+propext+` + `+Quot.sound+`
+(Lean’s core logical axioms) — *no `+Classical.choice+`, no `+sorryAx+`,
+no compiler-trust `+ofReduceBool+`* (kernel-checked throughout, even
+cleaner than `+WokeLang.lean+`).
+
+* *T3.3 termination* — the parser is a total function (fuel-structural
+mutual recursion ⇒ Lean accepts it ⇒ it terminates on every input).
+* *T6.1 precedence / T6.3 associativity* — a battery of
+kernel-`+decide+`d concrete checks: `+1+2*3 ↦ 1+(2*3)+`,
+`+1*2+3 ↦ (1*2)+3+`, `+1-2-3 ↦ (1-2)-3+`, `+8/4/2 ↦ (8/4)/2+`, the full
+six-level ladder, grouping, unary chains.
+* *T3.2 completeness* —
+`+completeness_rp : ∀ e, parseAll (rp e) = some e+` (universal, over the
+whole AST), built on `+prefix_rt+` (the parser inverts the renderer).
+The substantive verified-parser result.
+* *T2.2 unambiguity* — `+parse_deterministic+` (the parser is a function
+⇒ ≤1 parse) and `+rp_injective+` (distinct expressions have distinct
+concrete forms, proved via the parser).
+* *T3.1 soundness* — witnessed by the *rejection battery* (7
+kernel-`+decide+`d no-over-acceptance checks: leading op, two atoms,
+trailing op, unclosed/extra paren, empty, doubled op) + determinism.
+_Scope note:_ a full declarative-CFG soundness theorem
+(`+accepted ⇒ derivable+` against an independent grammar relation) is
+the one honest extension still open on P1; the rejection battery covers
+the no-junk direction concretely.
+
+=== Landed — P2/P3/P4 (`+WokeGrammarStructure.lean+`, Lean 4.30.0)
+
+CI-gated (`+lean-proofs.yml+`), `+sorry+`-free; `+no_left_recursion+`
+depends on *no axioms at all* (fully constructive).
+
+* *T2.1 no left recursion (P2)* — the begins-with-first-nonterminal
+graph of the _whole_ grammar is encoded as data with a
+strictly-decreasing rank; `+Reach+` (transitive first-symbol
+reachability) ⇒ `+no_left_recursion : ∀ a, ¬ Reach a a+`. *Discrepancy
+found & machine-checked:* the grammar _as literally written_ has one
+left-recursive production — the guard pattern
+`+pattern = … | pattern "when" expression+`
+(`+guard_pattern_is_left_recursive+`). So the prose §2.1 blanket "`no
+left recursion`" is *false as written*; it holds only for the
+implemented subset (the parser does not implement the guard alternative
+— the grammar’s own NOTE). This corrects the prose.
+* *T4.1 maximal munch / T4.2 keyword priority (P3)* — a word scanner
+taking the maximal identifier run + keyword-on-exact-match:
+`+kw_priority+` (general), `+munch_maximal+` (general longest-match: the
+remainder never extends the token), plus kernel-`+decide+`d concretes
+(`+remember+`↦keyword, `+remembering+`↦__one__ identifier not
+`+remember+`+`+ing+`, `+remember(+`↦keyword then stop).
+* *T1.2 LL(1)=✗ / T2.3 LL(2)=✓ (P4)* — `+not_LL1+` (the `+x+` vs
+`+x(…)+` FIRST/FIRST conflict shares FIRST₁ = identifier) and
+`+LL2_separates+` (two tokens decide, mirroring the parser’s
+`+peek == '('+` branch). CFG membership holds by construction.
+
+=== Landed — Coq mirror (`+WokeGrammarStructure.v+`, Coq 8.18.0)
+
+CI-gated (`+coq-proofs.yml+`); `+Print Assumptions+` reports
+*axiom-free* ("`Closed under the global context`"). Mirrors *P2
+(no-left-recursion + guard discrepancy)* and *P4 (LL(1)✗/LL(2)✓)* in
+lockstep with Lean. (The Lean↔Coq relationship for the _parser
+metatheory_ P1 follows the repo’s existing pattern — Lean carries the
+universal `+prefix_rt+`/`+completeness_rp+` development; a Coq port of
+that is the scoped next step, exactly as `+WokeLang.{lean,v}+` are
+"`complementary, not identical`" per `+AUDIT.md+`.)
+
+=== §7 — status (T7.1 done; §7.3 positive closure + CFL pumping lemma done)
+
+* *T7.1 not regular — DONE* (`+WokeGrammarRegular.lean+`): rather than
+fetch Mathlib’s automata library (blocked offline), a bespoke finite
+pigeonhole + a `+Fin k+` DFA + the fooling-set argument on `+aⁿbⁿ+` were
+built from scratch in core Lean, `+sorry+`-free (classical-logic axioms
+only). `+aⁿbⁿ ≅ (ⁿ x )ⁿ+`, the grammar’s balanced-nesting sublanguage,
+so the expression language is non-regular.
+* *§7.3 CFL _positive_ closure (∪, ·, *) — DONE*
+(`+WokeGrammarCFL.lean+`): a general CFG derivation relation + a
+reusable grammar-embedding lemma (`+embGen_iff+`) + explicit
+union/concat/star grammar constructions, `+sorry+`-free
+(`+propext+`-only). The WokeLang surface grammar is context-free, so it
+inhabits this class and these operations apply.
+* *Pumping lemma for CFLs — DONE* (`+WokeGrammarPumping.lean+`): the
+full pumping lemma (which even Mathlib lacks) is now machine-checked
+from scratch in core Lean. `+cfl_pumping+` states that for an ε-free
+binary-normal-form grammar with `+card+` nonterminals, any word
+`+z ∈ L(S)+` of length `+≥ 2^(card+1)+` splits as `+z = u v w x y+` with
+`+1 ≤ |v x|+`, `+|v w x| ≤ 2^(card+1)+`, and `+u vⁱ w xⁱ y ∈ L(S)+`
+for all `+i+`. Engine: parse trees + `+|w| < 2^height+` yield bound +
+one-hole contexts/`+fill+`/`+comp+` + `+pumpIter+` + tallest-spine
+`+descend+` (with the `+ht = height − depth+` and depth-composition
+laws) + finite pigeonhole ⇒ repeated-nonterminal extraction. Trust base:
+the three classical kernel constants (`+propext+`, `+Classical.choice+`,
+`+Quot.sound+`) — no holes, no project-specific assumptions.
+* *`+aⁿbⁿcⁿ ∉ CFL+` — DONE* (`+WokeGrammarPumping.lean+`,
+`+anbncn_not_cfl+`): the canonical non-context-free language, the crux
+of any ∩/¬ non-closure argument. `+IsCFL+` is defined finiteness-aware
+(an ε-free BNF grammar with an `+enum+`/`+card+` nonterminal bound,
+matching `+cfl_pumping+`; the relation-based `+IsCFL+` used for
+_positive_ closure is too permissive here — an infinite nonterminal type
+could "`generate`" `+aⁿbⁿcⁿ+`). Proof: apply `+cfl_pumping+` to
+`+aᵖbᵖcᵖ+`; pumping down to `+i = 0+` forces
+`+count_a = count_b = count_c+` in the deleted part, so the pumped
+window contains an `+a+` and a `+c+`; the positional core
+(`+prefix_pure+` by induction on the prefix, `+abc_window+`) then gives
+`+|vwx| > p+`, contradicting `+|vwx| ≤ p+`.
+* *§7.3 _non-closure_ under ∩ — DONE* (`+WokeGrammarPumping.lean+`,
+`+cfl_not_closed_inter+`): the context-free languages are not closed
+under intersection. Witnesses `+L₁ = {aⁱbⁱcʲ}+` and `+L₂ = {aᵐbⁿcⁿ}+`
+are each shown context-free by an explicit ε-free binary-normal-form
+grammar (`+R1+`, `+R2+`) with full _exact generation_ — soundness
+(`+sound_all1+`/`+sound_all2+`, one structural induction with inversion
+on the root production) and completeness (tree builders
+`+tree_X1+`/`+tree_Y1+`, `+tree_A2'+`/`+tree_W2+`). Their intersection
+is `+{aⁿbⁿcⁿ}+` (`+inter_eq+`, by equating the three letter-counts),
+which `+anbncn_not_cfl+` rules out. Closure under *complement* is
+refuted by the same witnesses via De Morgan against CFL ∪-closure (the
+standard corollary).
+
+=== Axiom audit (`+#print axioms+`, verified in-toolchain)
+
+Kernel-dependency printout for the headline results in
+`+WokeGrammarPumping.lean+` (Lean 4.30.0). Only the standard classical
+constants appear — no `+sorryAx+`, no project-specific constants:
+
+[cols=",",options="header",]
+|===
+|Theorem |Kernel dependencies
+|`+yield_bound+` |`+propext+`, `+Quot.sound+`
+
+|`+ht_descend+` |`+propext+`, `+Quot.sound+`
+
+|`+nodeNT_add+` |`+propext+`, `+Classical.choice+`, `+Quot.sound+`
+
+|`+descend_sibling_nonempty+` |`+propext+`, `+Quot.sound+`
+
+|`+cfl_pumping+` |`+propext+`, `+Classical.choice+`, `+Quot.sound+`
+
+|`+prefix_pure+` |`+propext+`
+
+|`+abc_window+` |`+propext+`, `+Quot.sound+`
+
+|`+anbncn_not_cfl+` |`+propext+`, `+Classical.choice+`, `+Quot.sound+`
+
+|`+isCFL_L1+`, `+isCFL_L2+` |`+propext+`, `+Quot.sound+`
+
+|`+inter_eq+` |`+propext+`, `+Quot.sound+`
+
+|`+cfl_not_closed_inter+` |`+propext+`, `+Classical.choice+`,
+`+Quot.sound+`
+|===
+
+`+Classical.choice+` enters only through the finite `+pigeon+`hole’s
+case split; the rest are the kernel constants Mathlib itself rests on.
+The other files’ headline results sit on the same or a smaller base
+(`+WokeGrammarCFL.lean+` is `+propext+`-only; `+WokeGrammarStructure+`’s
+`+no_left_recursion+` is fully constant-free).
+
+=== Status
+
+P1 (merged, #102) + P2/P3/P4 + the structural Coq mirror are
+machine-checked and CI-gated. P5/P6 are honestly flagged above. The
+authoritative status is always "`does the CI prover check go green.`"
diff --git a/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md b/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md
deleted file mode 100644
index f780e95..0000000
--- a/docs/proofs/verification/GRAMMAR-PROOF-INVENTORY.md
+++ /dev/null
@@ -1,241 +0,0 @@
-
-# WokeLang Grammar — Proof-Obligation Inventory & Audit
-
-This document is the **complete inventory** of every formal claim made *about the
-grammar* in [`grammar-proofs.md`](../formal-semantics/grammar-proofs.md), with,
-for each: whether it is **faithfully machine-checkable** in the repo's prover
-setup (Lean 4.30.0 / Coq 8.18.0, single-file, no Mathlib, offline), its
-**priority**, and its **status**.
-
-It answers the question the user posed: *which grammar proofs are needed, which
-are wanted, and which are actually done (run in a prover) vs. merely asserted in
-prose.*
-
-## Ground truth established first
-
-- **Canonical grammar:** `grammar/wokelang.ebnf`, *verified against the live
- implementation* (`src/lexer/token.rs` identifier rule `[a-zA-Z][a-zA-Z0-9_]*`;
- `src/parser/mod.rs` support for `while`/`break`/`continue`, lambdas, record
- literals, field access, function types). The older `spec/grammar.ebnf` was a
- **stale subset** falsely claiming to supersede it; it is now a generated
- synchronized copy guarded by `scripts/check-grammar-sync.sh`.
-- **Provers actually installed and run here:** Coq **8.18.0** (apt) and Lean
- **4.30.0** (pinned by `lean-toolchain`, installed from the GitHub release —
- the `*.lean-lang.org` resolver hosts are blocked by egress policy, so the
- tarball is fetched directly from `github.com`, exactly as `lean-proofs.yml`
- already does in CI). Baseline check before any new work: the **existing**
- `WokeLang.lean` and `WokeLang.v` both compile clean (exit 0), sorry/admit-free.
-- **Before this work there were ZERO machine-checked grammar proofs.** Every
- claim in `grammar-proofs.md` was English prose. The machine-checked
- `WokeLang.{lean,v}` cover the *type system / semantics* (on the AST), not the
- grammar/parser.
-
-## The parser being modelled (so the proofs are faithful, not invented)
-
-`src/parser/mod.rs` is a **precedence-climbing (Pratt) recursive-descent**
-parser. Precedence ladder (higher binds tighter):
-
-| Level | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
-|---|---|---|---|---|---|---|---|---|
-| | `or` | `and` | `== !=` | `< > <= >=` | `+ -` | `* / %` | unary `- not` | postfix `. () []` |
-
-Infix recursion uses **strict `<`** on the operator's own level ⇒ all binary
-operators are **left-associative**. This is exactly the EBNF repetition ladder
-(`logical_or = logical_and , { "or" , logical_and }` …). The Lean/Coq models
-reproduce this structure so soundness/completeness/precedence are about *this*
-parser, not a toy.
-
-## Inventory
-
-Legend — **Faithful?**: can it be mechanized *as the prose states it* in this
-setup? **Status**: `MACHINE-CHECKED` (compiles in a prover here) · `PROSE-ONLY`
-(was, and remains, an informal argument) · `FLAGGED` (honestly out of faithful
-reach here, with reason).
-
-| # | Prose claim (grammar-proofs.md) | Faithful here? | Priority | Mechanization | Status |
-|---|---|---|---|---|---|
-| T2.1 | §2.1 No left recursion | ✅ yes (whole grammar) | **P2** | Grammar as data; rank-decreasing `Reach` ⇒ `¬ Reach a a` over **all** productions | MACHINE-CHECKED (**+ found a real discrepancy:** the guard pattern IS left-recursive — see below) |
-| T2.2 | §2.2 Unambiguity | ✅ for the core (undecidable in general) | **P1** | Determinism of the verified parser ⇒ unique parse: `Derives ts e₁ → Derives ts e₂ → e₁=e₂` for the expression core | MACHINE-CHECKED (core) |
-| T2.3 | §2.3 LL(2) | ◑ partial | **P4** | The one 2-token decision (`ident` vs `ident(`) witnessed; determinism of the core parser. Full LL(2) table for all 94 productions is not built | MACHINE-CHECKED (witness) |
-| T3.1 | §3.1 Parser soundness | ✅ for the core | **P1** | `parse ts = some (e, rest) → Derives (consumed) e` | MACHINE-CHECKED (core) |
-| T3.2 | §3.2 Parser completeness | ✅ for the core | **P1** | `Derives ts e → parse ts = some (e, [])` | MACHINE-CHECKED (core) |
-| T3.3 | §3.3 Parser termination | ✅ | **P1** | Totality of `parse` (Lean/Coq accept the definition ⇒ it terminates on every input) + explicit fuel/measure | MACHINE-CHECKED |
-| T4.1 | §4.2 Maximal munch (longest match) | ✅ for the keyword/identifier fragment | **P3** | `classify` longest-prefix lemma; `"remembering"` ↦ identifier not `remember`+`ing` | MACHINE-CHECKED (fragment) |
-| T4.2 | §4.3 Keyword priority | ✅ | **P3** | `classify "remember" = Remember` and a general "a string equal to a keyword classifies as that keyword" lemma | MACHINE-CHECKED |
-| T6.1 | §6.2 Pratt precedence correctness | ✅ | **P1** | General precedence lemma + concrete `1+2*3 ↦ 1+(2*3)`, `1*2+3 ↦ (1*2)+3` | MACHINE-CHECKED |
-| T6.3 | §6.3 Left-associativity | ✅ | **P1** | `a-b-c ↦ (a-b)-c` from the strict-`<` model + general statement | MACHINE-CHECKED |
-| T1.1 | §1.1 CFG membership | ✅ | **P4** | By construction (the grammar relation is a CFG) | MACHINE-CHECKED |
-| T1.2 | §1.1 LL(1) = ✗ | ✅ | **P4** | Exhibit the FIRST/FIRST conflict (`primary → identifier` vs `identifier "(" …`) — a 1-lookahead non-determinism witness | MACHINE-CHECKED |
-| T7.3a | §7.3 CFL closed under ∪, ·, * | ✅ done from scratch | **P5→done** | `WokeGrammarCFL.lean`: CFG derivation relation + reusable embedding lemma + union/concat/star grammar constructions, `propext`-only | MACHINE-CHECKED |
-| T7.1 | §7.1 Not regular (pumping lemma) | ✅ done from scratch | **P6→done** | `WokeGrammarRegular.lean`: bespoke finite pigeonhole + `Fin k` DFA + fooling-set on `aⁿbⁿ` (≅ `(ⁿ)ⁿ`), Mathlib-free | MACHINE-CHECKED |
-| T7.0 | CFL pumping lemma (Mathlib-gap) | ✅ done from scratch | **Ext** | `WokeGrammarPumping.lean`: `cfl_pumping` — `descend`/`ht_descend`/`nodeNT_add` spine navigation + `Ctx.comp` + pigeonhole ⇒ `z = uvwxy`, `1≤|vx|`, `|vwx|≤2^(card+1)`, `uvⁱwxⁱy ∈ L`; classical kernel constants only | MACHINE-CHECKED |
-| T7.0b | `aⁿbⁿcⁿ ∉ CFL` (canonical non-CFL) | ✅ done from scratch | **Ext** | `WokeGrammarPumping.lean`: `anbncn_not_cfl` via `cfl_pumping` (pump `i=0` ⇒ equal counts ⇒ window spans `a`…`c` ⇒ `|vwx|>p`); positional core `prefix_pure`/`abc_window`; classical kernel constants only | MACHINE-CHECKED |
-| T7.3b | §7.3 CFL **not** closed under ∩ | ✅ done from scratch | **P6→done** | `WokeGrammarPumping.lean`: `cfl_not_closed_inter` — witnesses `L₁={aⁱbⁱcʲ}`, `L₂={aᵐbⁿcⁿ}` are CFL (explicit BNF grammars `R1`,`R2` + soundness via tree inversion + completeness via tree building), `L₁∩L₂={aⁿbⁿcⁿ}` not CFL (T7.0b) | MACHINE-CHECKED |
-
-## Priority order (execution)
-
-1. **P1 — expression-core verified parser** (`WokeGrammar.lean/.v`): discharges
- T3.1, T3.2, T3.3, T2.2(core), T6.1, T6.3, and feeds T2.3. Biggest and most
- load-bearing — the precedence/associativity/soundness story.
-2. **P2 — whole-grammar no-left-recursion** (T2.1): the only claim that is
- honestly provable for the *entire* 94-production grammar, not just a core.
-3. **P3 — lexer maximal-munch + keyword-priority** (T4.1, T4.2).
-4. **P4 — classification** (T1.1 CFG, T1.2 LL(1)✗, T2.3 LL(2) witness).
-5. **P5 — CFL positive closure** (T7.3a).
-6. **P6 — non-regularity + non-closure** (T7.1, T7.0/T7.0b, T7.3b): originally
- flagged, now all machine-checked from scratch (DFA fooling-set; CFL pumping
- lemma; `aⁿbⁿcⁿ ∉ CFL`; ∩ non-closure with explicit witness grammars).
-
-Then **mirror P1–P5 to Coq** (the repo keeps Lean/Coq in lockstep) and **gate
-both in CI**.
-
-## What is deliberately NOT claimed
-
-- **Completeness against the *Rust* parser byte-for-byte** is *not* asserted: the
- proofs are against a Lean/Coq model that faithfully reproduces the parser's
- precedence-climbing structure. Bridging model↔Rust would need a verified
- extraction or a Rust semantics, which neither prover provides here. The model
- is justified by the structural correspondence documented above, not by
- extraction.
-- **Full-CFG unambiguity** (T2.2 for the *entire* grammar) is undecidable; only
- the core is proven unambiguous (via parser determinism).
-- The **non-regularity / non-closure** results (T7.1, T7.3b) were initially
- flagged; they are now fully machine-checked from scratch (see P6) — never faked.
-
-## Landed — P1 (`WokeGrammar.lean`, Lean 4.30.0)
-
-Machine-checked and CI-gated (`.github/workflows/lean-proofs.yml`). Compiles
-clean (`lean WokeGrammar.lean`, exit 0), **`sorry`/`admit`/`native_decide`-free**.
-`#print axioms` on the headline theorems shows dependence only on `propext` +
-`Quot.sound` (Lean's core logical axioms) — **no `Classical.choice`, no
-`sorryAx`, no compiler-trust `ofReduceBool`** (kernel-checked throughout, even
-cleaner than `WokeLang.lean`).
-
-- **T3.3 termination** — the parser is a total function (fuel-structural mutual
- recursion ⇒ Lean accepts it ⇒ it terminates on every input).
-- **T6.1 precedence / T6.3 associativity** — a battery of kernel-`decide`d
- concrete checks: `1+2*3 ↦ 1+(2*3)`, `1*2+3 ↦ (1*2)+3`, `1-2-3 ↦ (1-2)-3`,
- `8/4/2 ↦ (8/4)/2`, the full six-level ladder, grouping, unary chains.
-- **T3.2 completeness** — `completeness_rp : ∀ e, parseAll (rp e) = some e`
- (universal, over the whole AST), built on `prefix_rt` (the parser inverts the
- renderer). The substantive verified-parser result.
-- **T2.2 unambiguity** — `parse_deterministic` (the parser is a function ⇒ ≤1
- parse) and `rp_injective` (distinct expressions have distinct concrete forms,
- proved via the parser).
-- **T3.1 soundness** — witnessed by the **rejection battery** (7 kernel-`decide`d
- no-over-acceptance checks: leading op, two atoms, trailing op, unclosed/extra
- paren, empty, doubled op) + determinism. *Scope note:* a full declarative-CFG
- soundness theorem (`accepted ⇒ derivable` against an independent grammar
- relation) is the one honest extension still open on P1; the rejection battery
- covers the no-junk direction concretely.
-
-## Landed — P2/P3/P4 (`WokeGrammarStructure.lean`, Lean 4.30.0)
-
-CI-gated (`lean-proofs.yml`), `sorry`-free; `no_left_recursion` depends on **no
-axioms at all** (fully constructive).
-
-- **T2.1 no left recursion (P2)** — the begins-with-first-nonterminal graph of the
- *whole* grammar is encoded as data with a strictly-decreasing rank; `Reach`
- (transitive first-symbol reachability) ⇒ `no_left_recursion : ∀ a, ¬ Reach a a`.
- **Discrepancy found & machine-checked:** the grammar *as literally written* has
- one left-recursive production — the guard pattern `pattern = … | pattern "when"
- expression` (`guard_pattern_is_left_recursive`). So the prose §2.1 blanket "no
- left recursion" is **false as written**; it holds only for the implemented
- subset (the parser does not implement the guard alternative — the grammar's own
- NOTE). This corrects the prose.
-- **T4.1 maximal munch / T4.2 keyword priority (P3)** — a word scanner taking the
- maximal identifier run + keyword-on-exact-match: `kw_priority` (general),
- `munch_maximal` (general longest-match: the remainder never extends the token),
- plus kernel-`decide`d concretes (`remember`↦keyword, `remembering`↦*one*
- identifier not `remember`+`ing`, `remember(`↦keyword then stop).
-- **T1.2 LL(1)=✗ / T2.3 LL(2)=✓ (P4)** — `not_LL1` (the `x` vs `x(…)` FIRST/FIRST
- conflict shares FIRST₁ = identifier) and `LL2_separates` (two tokens decide,
- mirroring the parser's `peek == '('` branch). CFG membership holds by
- construction.
-
-## Landed — Coq mirror (`WokeGrammarStructure.v`, Coq 8.18.0)
-
-CI-gated (`coq-proofs.yml`); `Print Assumptions` reports **axiom-free** ("Closed
-under the global context"). Mirrors **P2 (no-left-recursion + guard discrepancy)**
-and **P4 (LL(1)✗/LL(2)✓)** in lockstep with Lean. (The Lean↔Coq relationship for
-the *parser metatheory* P1 follows the repo's existing pattern — Lean carries the
-universal `prefix_rt`/`completeness_rp` development; a Coq port of that is the
-scoped next step, exactly as `WokeLang.{lean,v}` are "complementary, not
-identical" per `AUDIT.md`.)
-
-## §7 — status (T7.1 done; §7.3 positive closure + CFL pumping lemma done)
-
-- **T7.1 not regular — DONE** (`WokeGrammarRegular.lean`): rather than fetch
- Mathlib's automata library (blocked offline), a bespoke finite pigeonhole + a
- `Fin k` DFA + the fooling-set argument on `aⁿbⁿ` were built from scratch in
- core Lean, `sorry`-free (classical-logic axioms only). `aⁿbⁿ ≅ (ⁿ x )ⁿ`, the
- grammar's balanced-nesting sublanguage, so the expression language is non-regular.
-- **§7.3 CFL *positive* closure (∪, ·, \*) — DONE** (`WokeGrammarCFL.lean`): a
- general CFG derivation relation + a reusable grammar-embedding lemma
- (`embGen_iff`) + explicit union/concat/star grammar constructions, `sorry`-free
- (`propext`-only). The WokeLang surface grammar is context-free, so it inhabits
- this class and these operations apply.
-- **Pumping lemma for CFLs — DONE** (`WokeGrammarPumping.lean`): the full pumping
- lemma (which even Mathlib lacks) is now machine-checked from scratch in core
- Lean. `cfl_pumping` states that for an ε-free binary-normal-form grammar with
- `card` nonterminals, any word `z ∈ L(S)` of length `≥ 2^(card+1)` splits as
- `z = u v w x y` with `1 ≤ |v x|`, `|v w x| ≤ 2^(card+1)`, and `u vⁱ w xⁱ y ∈
- L(S)` for all `i`. Engine: parse trees + `|w| < 2^height` yield bound + one-hole
- contexts/`fill`/`comp` + `pumpIter` + tallest-spine `descend` (with the
- `ht = height − depth` and depth-composition laws) + finite pigeonhole ⇒
- repeated-nonterminal extraction. Trust base: the three classical kernel
- constants (`propext`, `Classical.choice`, `Quot.sound`) — no holes, no
- project-specific assumptions.
-- **`aⁿbⁿcⁿ ∉ CFL` — DONE** (`WokeGrammarPumping.lean`, `anbncn_not_cfl`): the
- canonical non-context-free language, the crux of any ∩/¬ non-closure argument.
- `IsCFL` is defined finiteness-aware (an ε-free BNF grammar with an `enum`/`card`
- nonterminal bound, matching `cfl_pumping`; the relation-based `IsCFL` used for
- *positive* closure is too permissive here — an infinite nonterminal type could
- "generate" `aⁿbⁿcⁿ`). Proof: apply `cfl_pumping` to `aᵖbᵖcᵖ`; pumping down to
- `i = 0` forces `count_a = count_b = count_c` in the deleted part, so the pumped
- window contains an `a` and a `c`; the positional core (`prefix_pure` by induction
- on the prefix, `abc_window`) then gives `|vwx| > p`, contradicting `|vwx| ≤ p`.
-- **§7.3 *non-closure* under ∩ — DONE** (`WokeGrammarPumping.lean`,
- `cfl_not_closed_inter`): the context-free languages are not closed under
- intersection. Witnesses `L₁ = {aⁱbⁱcʲ}` and `L₂ = {aᵐbⁿcⁿ}` are each shown
- context-free by an explicit ε-free binary-normal-form grammar (`R1`, `R2`) with
- full *exact generation* — soundness (`sound_all1`/`sound_all2`, one structural
- induction with inversion on the root production) and completeness (tree builders
- `tree_X1`/`tree_Y1`, `tree_A2'`/`tree_W2`). Their intersection is `{aⁿbⁿcⁿ}`
- (`inter_eq`, by equating the three letter-counts), which `anbncn_not_cfl` rules
- out. Closure under **complement** is refuted by the same witnesses via De Morgan
- against CFL ∪-closure (the standard corollary).
-
-## Axiom audit (`#print axioms`, verified in-toolchain)
-
-Kernel-dependency printout for the headline results in `WokeGrammarPumping.lean`
-(Lean 4.30.0). Only the standard classical constants appear — no `sorryAx`, no
-project-specific constants:
-
-| Theorem | Kernel dependencies |
-|---|---|
-| `yield_bound` | `propext`, `Quot.sound` |
-| `ht_descend` | `propext`, `Quot.sound` |
-| `nodeNT_add` | `propext`, `Classical.choice`, `Quot.sound` |
-| `descend_sibling_nonempty` | `propext`, `Quot.sound` |
-| `cfl_pumping` | `propext`, `Classical.choice`, `Quot.sound` |
-| `prefix_pure` | `propext` |
-| `abc_window` | `propext`, `Quot.sound` |
-| `anbncn_not_cfl` | `propext`, `Classical.choice`, `Quot.sound` |
-| `isCFL_L1`, `isCFL_L2` | `propext`, `Quot.sound` |
-| `inter_eq` | `propext`, `Quot.sound` |
-| `cfl_not_closed_inter` | `propext`, `Classical.choice`, `Quot.sound` |
-
-`Classical.choice` enters only through the finite `pigeon`hole's case split; the
-rest are the kernel constants Mathlib itself rests on. The other files' headline
-results sit on the same or a smaller base (`WokeGrammarCFL.lean` is `propext`-only;
-`WokeGrammarStructure`'s `no_left_recursion` is fully constant-free).
-
-## Status
-
-P1 (merged, #102) + P2/P3/P4 + the structural Coq mirror are machine-checked and
-CI-gated. P5/P6 are honestly flagged above. The authoritative status is always
-"does the CI prover check go green."
diff --git a/docs/reports/audit/audit-2026-04-04.adoc b/docs/reports/audit/audit-2026-04-04.adoc
new file mode 100644
index 0000000..e2b6333
--- /dev/null
+++ b/docs/reports/audit/audit-2026-04-04.adoc
@@ -0,0 +1,137 @@
+== Audit Report: wokelang — 2026-04-04
+
+=== Classification: M2 Estate Audit — Wider Tranche
+
+'''''
+
+=== Dangerous Patterns
+
+[width="100%",cols="40%,30%,30%",options="header",]
+|===
+|Pattern |Count |Notes
+|`+unwrap()+` |~350 |Concentrated in stdlib/chan (86), parser (140),
+interpreter (28)
+
+|`+expect()+` |~50 |Spread across modules
+
+|`+todo!()+` |~12 |Non-production scaffolding
+
+|`+unimplemented!()+` |~0 |None significant
+|===
+
+*Total: ~412 calls.* HIGH. Primary concern: parser and interpreter
+paths. stdlib/chan `+unwrap()+` count (86) is critical — concurrency
+primitives must not panic.
+
+*Remediation priority:* P1 — parser and stdlib/chan unwrap removal
+before any publication.
+
+'''''
+
+=== Test Coverage
+
+[cols=",",options="header",]
+|===
+|Category |Count
+|Unit tests (`+#[test]+`) |173
+|Test files |31
+|E2E tests |Partial (CI wired 2026-04-04)
+|Property tests |None
+|Benchmarks |None
+|===
+
+*CRG Grade: C* (achieved 2026-04-04). 173 tests is solid for a language
+implementation. Grammar audit C5 DONE: send/receive/await/cancel
+concurrency primitives implemented
+(lexer→AST→parser→visitor→formatter→linter→typechecker).
+
+'''''
+
+=== Template Residue
+
+[cols=",",options="header",]
+|===
+|Type |Count
+|TODO/FIXME markers |~15
+|`+{{OWNER}}+`/`+{{REPO}}+` placeholders |0
+|Placeholder comments |0
+|===
+
+Clean. TODO markers are legitimate development notes, not scaffolding
+residue.
+
+'''''
+
+=== RSR Compliance
+
+[cols=",",options="header",]
+|===
+|File |Present
+|`+EXPLAINME.adoc+` |YES
+|`+SECURITY.md+` |YES
+|`+CONTRIBUTING.md+` |YES
+|`+0-AI-MANIFEST.a2ml+` |YES
+|===
+
+*Full RSR compliance.*
+
+'''''
+
+=== Proof Debt
+
+[width="100%",cols="29%,33%,38%",options="header",]
+|===
+|Item |Count |Detail
+|PROOF-NEEDS.md items |4 |Consent-semantics formalization, linear
+resource tracking, session types, effect system
+
+|`+Admitted+` / `+sorry+` |0 |No Coq/Lean proofs in repo
+
+|`+postulate+` |0 |No Idris2 proofs in repo
+|===
+
+*Low proof debt.* Formal proofs deferred — the PROOF-NEEDS.md correctly
+documents what needs proving, but none has been started.
+
+'''''
+
+=== Publication Safety
+
+[width="100%",cols="43%,57%",options="header",]
+|===
+|Item |Status
+|ArXiv paper |1 (`+arxiv-consent-aware-programming.tex+`)
+
+|Overclaiming |None detected
+
+|Test/claim parity |Acceptable — paper makes language design claims, not
+performance benchmarks
+
+|Missing evidence |Formal proofs for consent semantics not yet done
+|===
+
+*Publication status: NOT YET READY.* The
+`+arxiv-consent-aware-programming.tex+` paper requires: 1. Proof of
+consent-semantic soundness (at minimum, an informal argument with test
+evidence) 2. unwrap() reduction in concurrency primitives (affects
+paper’s correctness claims) 3. Property tests for send/recv/await/cancel
+(PROOF-NEEDS items 1-2)
+
+'''''
+
+=== Summary
+
+[cols=",,",options="header",]
+|===
+|Dimension |Grade |Notes
+|Dangerous patterns |D |412 calls, parser+stdlib/chan critical
+|Test coverage |C |173 tests, grammar complete
+|RSR compliance |A |All 4 required files present
+|Proof debt |C |4 items planned, 0 started
+|Publication safety |D |Paper requires proof evidence
+|===
+
+*Overall: NOT publication-safe.* Hold
+`+arxiv-consent-aware-programming.tex+` until: unwrap reduction in
+critical paths, property tests for concurrency primitives, informal
+proof of consent-semantic soundness.
diff --git a/docs/reports/audit/audit-2026-04-04.md b/docs/reports/audit/audit-2026-04-04.md
deleted file mode 100644
index 28a4e31..0000000
--- a/docs/reports/audit/audit-2026-04-04.md
+++ /dev/null
@@ -1,103 +0,0 @@
-
-# Audit Report: wokelang — 2026-04-04
-
-## Classification: M2 Estate Audit — Wider Tranche
-
----
-
-## Dangerous Patterns
-
-| Pattern | Count | Notes |
-|---------|-------|-------|
-| `unwrap()` | ~350 | Concentrated in stdlib/chan (86), parser (140), interpreter (28) |
-| `expect()` | ~50 | Spread across modules |
-| `todo!()` | ~12 | Non-production scaffolding |
-| `unimplemented!()` | ~0 | None significant |
-
-**Total: ~412 calls.** HIGH. Primary concern: parser and interpreter paths. stdlib/chan `unwrap()` count (86) is critical — concurrency primitives must not panic.
-
-**Remediation priority:** P1 — parser and stdlib/chan unwrap removal before any publication.
-
----
-
-## Test Coverage
-
-| Category | Count |
-|----------|-------|
-| Unit tests (`#[test]`) | 173 |
-| Test files | 31 |
-| E2E tests | Partial (CI wired 2026-04-04) |
-| Property tests | None |
-| Benchmarks | None |
-
-**CRG Grade: C** (achieved 2026-04-04). 173 tests is solid for a language implementation. Grammar audit C5 DONE: send/receive/await/cancel concurrency primitives implemented (lexer→AST→parser→visitor→formatter→linter→typechecker).
-
----
-
-## Template Residue
-
-| Type | Count |
-|------|-------|
-| TODO/FIXME markers | ~15 |
-| `{{OWNER}}`/`{{REPO}}` placeholders | 0 |
-| Placeholder comments | 0 |
-
-Clean. TODO markers are legitimate development notes, not scaffolding residue.
-
----
-
-## RSR Compliance
-
-| File | Present |
-|------|---------|
-| `EXPLAINME.adoc` | YES |
-| `SECURITY.md` | YES |
-| `CONTRIBUTING.md` | YES |
-| `0-AI-MANIFEST.a2ml` | YES |
-
-**Full RSR compliance.**
-
----
-
-## Proof Debt
-
-| Item | Count | Detail |
-|------|-------|--------|
-| PROOF-NEEDS.md items | 4 | Consent-semantics formalization, linear resource tracking, session types, effect system |
-| `Admitted` / `sorry` | 0 | No Coq/Lean proofs in repo |
-| `postulate` | 0 | No Idris2 proofs in repo |
-
-**Low proof debt.** Formal proofs deferred — the PROOF-NEEDS.md correctly documents what needs proving, but none has been started.
-
----
-
-## Publication Safety
-
-| Item | Status |
-|------|--------|
-| ArXiv paper | 1 (`arxiv-consent-aware-programming.tex`) |
-| Overclaiming | None detected |
-| Test/claim parity | Acceptable — paper makes language design claims, not performance benchmarks |
-| Missing evidence | Formal proofs for consent semantics not yet done |
-
-**Publication status: NOT YET READY.** The `arxiv-consent-aware-programming.tex` paper requires:
-1. Proof of consent-semantic soundness (at minimum, an informal argument with test evidence)
-2. unwrap() reduction in concurrency primitives (affects paper's correctness claims)
-3. Property tests for send/recv/await/cancel (PROOF-NEEDS items 1-2)
-
----
-
-## Summary
-
-| Dimension | Grade | Notes |
-|-----------|-------|-------|
-| Dangerous patterns | D | 412 calls, parser+stdlib/chan critical |
-| Test coverage | C | 173 tests, grammar complete |
-| RSR compliance | A | All 4 required files present |
-| Proof debt | C | 4 items planned, 0 started |
-| Publication safety | D | Paper requires proof evidence |
-
-**Overall: NOT publication-safe.** Hold `arxiv-consent-aware-programming.tex` until: unwrap reduction in critical paths, property tests for concurrency primitives, informal proof of consent-semantic soundness.
diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc
new file mode 100644
index 0000000..61101c3
--- /dev/null
+++ b/docs/tech-debt-2026-05-26.adoc
@@ -0,0 +1,80 @@
+== Tech-Debt Audit — wokelang — 2026-05-26
+
+*Source:* estate-wide automated scan 2026-05-26. *Companion:*
+https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+`
+2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`.
+
+This file records the _raw findings_ — it does not by itself fix the
+debt. Each section ends with a '`Recommended next move`' line; closing
+the debt is follow-up work.
+
+=== 1. Proof debt
+
+Scanner counted the following markers in proof-bearing files of this
+repo:
+
+....
+files= 9 | Coq-Axm/Adm= 0 | Lean-srry/ax= 1 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0
+....
+
+*Total markers:* 1. *Severity:* `+>01+`.
+
+*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+`
+— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s
+equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2
+`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality
+assumption. - Idris2 top-level `+partial+` — totality-check waived. - F*
+`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` —
+self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` —
+soundness-relevant escape hatches in Haskell/Rust source.
+
+*Recommended next move:* triage each finding into one of: (a) discharge
+by proof, (b) cover with property-tests + a documented refutation
+budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in
+`+docs/proof-debt.md+`.
+
+=== 2. Licence debt
+
+[cols=",",options="header",]
+|===
+|Field |Value
+|LICENSE file |`+LICENSE+`
+|SPDX header |`+MPL-2.0+`
+|Manifest licence |`+MPL-2.0+`
+|Body classifier |`+Palimp-MPL-2.0+`
+|Severity |`+ok+`
+|===
+
+*Recommended next move:* none for licence.
+
+=== 3. Documentation debt
+
+[cols=",",options="header",]
+|===
+|Field |Value
+|README lines |209
+|`+docs/+` files |58
+|`+docs/+` LoC |20193
+|CHANGELOG.md |Y
+|CONTRIBUTING.md |Y
+|CODE_OF_CONDUCT.md |Y
+|SECURITY.md |Y
+|Severity |`+OK+`
+|===
+
+*Recommended next move:* none for docs.
+
+=== Cross-references
+
+* Estate proof-debt audit:
+`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+`
+* Estate licence-debt audit:
+`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+`
+* Estate documentation-debt audit:
+`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+`
+
+'''''
+
+🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26).
+This file is informational — closing the debt is follow-up work owned by
+the maintainer.
diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md
deleted file mode 100644
index ca2d9ea..0000000
--- a/docs/tech-debt-2026-05-26.md
+++ /dev/null
@@ -1,70 +0,0 @@
-
-# Tech-Debt Audit — wokelang — 2026-05-26
-
-**Source:** estate-wide automated scan 2026-05-26.
-**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits).
-**Combined severity:** `LOW`.
-
-This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work.
-
-## 1. Proof debt
-
-Scanner counted the following markers in proof-bearing files of this repo:
-
-```
-files= 9 | Coq-Axm/Adm= 0 | Lean-srry/ax= 1 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0
-```
-
-**Total markers:** 1. **Severity:** `>01`.
-
-**Marker types** (any non-zero counts above):
-- Coq `Axiom`/`Admitted` — unconditional proof escapes.
-- Lean `sorry`/`axiom` — Lean's equivalent.
-- Agda `postulate` — accepted axiomatically.
-- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption.
-- Idris2 top-level `partial` — totality-check waived.
-- F\* `assume val`/`admit_p` — F\* admit.
-- `TODO PROOF` / `OWED:` — self-documented debt markers.
-- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source.
-
-**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`.
-
-## 2. Licence debt
-
-| Field | Value |
-|---|---|
-| LICENSE file | `LICENSE` |
-| SPDX header | `MPL-2.0` |
-| Manifest licence | `MPL-2.0` |
-| Body classifier | `Palimp-MPL-2.0` |
-| Severity | `ok` |
-
-**Recommended next move:** none for licence.
-
-## 3. Documentation debt
-
-| Field | Value |
-|---|---|
-| README lines | 209 |
-| `docs/` files | 58 |
-| `docs/` LoC | 20193 |
-| CHANGELOG.md | Y |
-| CONTRIBUTING.md | Y |
-| CODE_OF_CONDUCT.md | Y |
-| SECURITY.md | Y |
-| Severity | `OK` |
-
-**Recommended next move:** none for docs.
-
-## Cross-references
-
-- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md`
-- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md`
-- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md`
-
----
-
-🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer.
diff --git a/editors/vscode/README.adoc b/editors/vscode/README.adoc
new file mode 100644
index 0000000..19d1d36
--- /dev/null
+++ b/editors/vscode/README.adoc
@@ -0,0 +1,79 @@
+== WokeLang for Visual Studio Code
+
+VS Code language support for WokeLang — a human-centered programming
+language with consent-driven capabilities.
+
+____
+*Status (2026-06): syntax support only.* This extension currently
+provides *syntax highlighting* and *language configuration* for
+`+.woke+` files. The full LSP client (completion, hover, diagnostics,
+go-to-definition, formatting) has been *removed* because its previous
+implementation was in ReScript, which is banned estate-wide.
+
+The intended reimplementation language is *AffineScript*
+(estate-primary), but AffineScript currently has no host-FFI mechanism
+and compiles to WASM rather than the JS extension host, so a faithful
+client cannot be written yet. It is *blocked on the planned estate
+ABI/FFI layer* and tracked in the repository issues. The `+woke-lsp+`
+server binary itself (Rust) is unaffected and continues to build via
+`+cargo build --bin woke-lsp+`.
+____
+
+=== Features (current)
+
+* *Syntax highlighting* — TextMate grammar for `+.woke+` files
+(`+syntaxes/wokelang.tmLanguage.json+`).
+* *Language configuration* — brackets, comments, auto-closing pairs
+(`+language-configuration.json+`).
+
+=== Installation
+
+No build step is required for the passive extension. Copy it into your
+VS Code extensions directory:
+
+[source,bash]
+----
+cp -r /path/to/wokelang/editors/vscode ~/.vscode/extensions/wokelang-0.1.0/
+----
+
+Then reload VS Code. Open any `+.woke+` file to get syntax highlighting.
+
+=== Example
+
+[source,wokelang]
+----
+// Define a function
+to calculateArea(width, height) {
+ give back width * height;
+}
+
+to main() {
+ remember result = calculateArea(5, 10);
+ when result > 20 {
+ print("Large area");
+ } otherwise {
+ print("Small area");
+ }
+}
+----
+
+=== Roadmap
+
+* *LSP client (AffineScript)* — restore completion / hover / diagnostics
+/ go-to-definition / formatting by driving the Rust `+woke-lsp+` server
+from an AffineScript-authored client, once the estate ABI/FFI layer
+lands. Until then the server can be used with any LSP-capable editor
+that lets you point at the `+woke-lsp+` binary directly.
+
+=== License
+
+MPL-2.0
+
+=== Links
+
+* https://github.com/hyperpolymath/wokelang[WokeLang Repository]
+* https://github.com/hyperpolymath/wokelang/issues[Report Issues]
+
+=== Credits
+
+*Author:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
deleted file mode 100644
index 865bb7f..0000000
--- a/editors/vscode/README.md
+++ /dev/null
@@ -1,78 +0,0 @@
-
-# WokeLang for Visual Studio Code
-
-VS Code language support for WokeLang — a human-centered programming language
-with consent-driven capabilities.
-
-> **Status (2026-06): syntax support only.**
-> This extension currently provides **syntax highlighting** and **language
-> configuration** for `.woke` files. The full LSP client (completion, hover,
-> diagnostics, go-to-definition, formatting) has been **removed** because its
-> previous implementation was in ReScript, which is banned estate-wide.
->
-> The intended reimplementation language is **AffineScript** (estate-primary),
-> but AffineScript currently has no host-FFI mechanism and compiles to WASM
-> rather than the JS extension host, so a faithful client cannot be written
-> yet. It is **blocked on the planned estate ABI/FFI layer** and tracked in the
-> repository issues. The `woke-lsp` server binary itself (Rust) is unaffected
-> and continues to build via `cargo build --bin woke-lsp`.
-
-## Features (current)
-
-- **Syntax highlighting** — TextMate grammar for `.woke` files
- (`syntaxes/wokelang.tmLanguage.json`).
-- **Language configuration** — brackets, comments, auto-closing pairs
- (`language-configuration.json`).
-
-## Installation
-
-No build step is required for the passive extension. Copy it into your VS Code
-extensions directory:
-
-```bash
-cp -r /path/to/wokelang/editors/vscode ~/.vscode/extensions/wokelang-0.1.0/
-```
-
-Then reload VS Code. Open any `.woke` file to get syntax highlighting.
-
-## Example
-
-```wokelang
-// Define a function
-to calculateArea(width, height) {
- give back width * height;
-}
-
-to main() {
- remember result = calculateArea(5, 10);
- when result > 20 {
- print("Large area");
- } otherwise {
- print("Small area");
- }
-}
-```
-
-## Roadmap
-
-- **LSP client (AffineScript)** — restore completion / hover / diagnostics /
- go-to-definition / formatting by driving the Rust `woke-lsp` server from an
- AffineScript-authored client, once the estate ABI/FFI layer lands. Until then
- the server can be used with any LSP-capable editor that lets you point at the
- `woke-lsp` binary directly.
-
-## License
-
-MPL-2.0
-
-## Links
-
-- [WokeLang Repository](https://github.com/hyperpolymath/wokelang)
-- [Report Issues](https://github.com/hyperpolymath/wokelang/issues)
-
-## Credits
-
-**Author:** Jonathan D.A. Jewell
diff --git a/examples/README.adoc b/examples/README.adoc
new file mode 100644
index 0000000..74eb1bb
--- /dev/null
+++ b/examples/README.adoc
@@ -0,0 +1,110 @@
+== WokeLang Example Programs
+
+This directory contains example programs demonstrating WokeLang’s
+features.
+
+=== Running Examples
+
+==== Using the Interpreter (Tree-Walking)
+
+[source,bash]
+----
+woke run examples/01_hello.woke
+----
+
+==== Using the VM (Bytecode)
+
+[source,bash]
+----
+woke run-vm examples/01_hello.woke
+----
+
+==== Type Checking
+
+[source,bash]
+----
+woke typecheck examples/01_hello.woke
+----
+
+==== Linting
+
+[source,bash]
+----
+woke lint examples/01_hello.woke
+----
+
+=== Examples
+
+==== 01_hello.woke ✓ Interpreter ✓ VM
+
+The simplest possible WokeLang program. Returns the answer to
+everything.
+
+==== 02_arithmetic.woke ✓ Interpreter ✓ VM
+
+Basic arithmetic operations: addition, subtraction, multiplication,
+division, modulo.
+
+==== 03_conditionals.woke ✓ Interpreter ✓ VM
+
+Conditional execution with `+when/otherwise+` (if/else) statements.
+
+==== 04_loops.woke ✓ Interpreter ⚠ VM (partial)
+
+Repetition with `+repeat...times+` loops. Includes a factorial
+implementation. _Note: VM loop implementation in progress_
+
+==== 05_functions.woke ✓ Interpreter ⚠ VM (not yet)
+
+Function definitions, parameters, return types, and function calls.
+_Note: VM function calls not yet implemented_
+
+==== 06_variables.woke ✓ Interpreter ✓ VM
+
+Variable declaration with `+remember+` and reassignment.
+
+==== 07_arrays.woke ✓ Interpreter ⚠ VM (not yet)
+
+Array creation, indexing, and manipulation. _Note: VM array indexing not
+yet implemented_
+
+==== 08_consent.woke ✓ Interpreter ✓ VM
+
+Consent gates with `+only if okay+` for permission-protected operations.
+
+=== Language Features
+
+==== Human-Centered Syntax
+
+* `+to function_name()+` - Define a function
+* `+remember x = value+` - Declare a variable
+* `+give back value+` - Return from a function
+* `+when condition { ... } otherwise { ... }+` - Conditional
+* `+repeat n times { ... }+` - Loop
+* `+only if okay "permission" { ... }+` - Consent gate
+
+==== Types
+
+* `+Int+` - Integer numbers
+* `+Float+` - Floating-point numbers
+* `+String+` - Text strings
+* `+Bool+` - Boolean values (true/false)
+* `+Array+` - Collections
+* `+Result+` - Success/error values (Okay/Oops)
+
+==== Unique Features
+
+* *Consent-Driven*: `+only if okay+` gates for capability-based security
+* *Gratitude Blocks*: `+thanks to { ... }+` for acknowledgments
+* *Emote Annotations*: `+@emote+` for emotional context
+* *Units of Measure*: `+measured in meters+` for dimensional types
+
+=== Contributing
+
+Feel free to add more examples! Follow these guidelines: - Number
+examples sequentially - Include comments explaining the code - Keep
+examples focused on a single feature - Test examples before committing
+
+=== License
+
+MPL-2.0
diff --git a/examples/README.md b/examples/README.md
deleted file mode 100644
index 44b9d7c..0000000
--- a/examples/README.md
+++ /dev/null
@@ -1,94 +0,0 @@
-
-# WokeLang Example Programs
-
-This directory contains example programs demonstrating WokeLang's features.
-
-## Running Examples
-
-### Using the Interpreter (Tree-Walking)
-```bash
-woke run examples/01_hello.woke
-```
-
-### Using the VM (Bytecode)
-```bash
-woke run-vm examples/01_hello.woke
-```
-
-### Type Checking
-```bash
-woke typecheck examples/01_hello.woke
-```
-
-### Linting
-```bash
-woke lint examples/01_hello.woke
-```
-
-## Examples
-
-### 01_hello.woke ✓ Interpreter ✓ VM
-The simplest possible WokeLang program. Returns the answer to everything.
-
-### 02_arithmetic.woke ✓ Interpreter ✓ VM
-Basic arithmetic operations: addition, subtraction, multiplication, division, modulo.
-
-### 03_conditionals.woke ✓ Interpreter ✓ VM
-Conditional execution with `when/otherwise` (if/else) statements.
-
-### 04_loops.woke ✓ Interpreter ⚠ VM (partial)
-Repetition with `repeat...times` loops. Includes a factorial implementation.
-*Note: VM loop implementation in progress*
-
-### 05_functions.woke ✓ Interpreter ⚠ VM (not yet)
-Function definitions, parameters, return types, and function calls.
-*Note: VM function calls not yet implemented*
-
-### 06_variables.woke ✓ Interpreter ✓ VM
-Variable declaration with `remember` and reassignment.
-
-### 07_arrays.woke ✓ Interpreter ⚠ VM (not yet)
-Array creation, indexing, and manipulation.
-*Note: VM array indexing not yet implemented*
-
-### 08_consent.woke ✓ Interpreter ✓ VM
-Consent gates with `only if okay` for permission-protected operations.
-
-## Language Features
-
-### Human-Centered Syntax
-- `to function_name()` - Define a function
-- `remember x = value` - Declare a variable
-- `give back value` - Return from a function
-- `when condition { ... } otherwise { ... }` - Conditional
-- `repeat n times { ... }` - Loop
-- `only if okay "permission" { ... }` - Consent gate
-
-### Types
-- `Int` - Integer numbers
-- `Float` - Floating-point numbers
-- `String` - Text strings
-- `Bool` - Boolean values (true/false)
-- `Array` - Collections
-- `Result` - Success/error values (Okay/Oops)
-
-### Unique Features
-- **Consent-Driven**: `only if okay` gates for capability-based security
-- **Gratitude Blocks**: `thanks to { ... }` for acknowledgments
-- **Emote Annotations**: `@emote` for emotional context
-- **Units of Measure**: `measured in meters` for dimensional types
-
-## Contributing
-
-Feel free to add more examples! Follow these guidelines:
-- Number examples sequentially
-- Include comments explaining the code
-- Keep examples focused on a single feature
-- Test examples before committing
-
-## License
-
-MPL-2.0
diff --git a/lib/README.adoc b/lib/README.adoc
new file mode 100644
index 0000000..f8bc880
--- /dev/null
+++ b/lib/README.adoc
@@ -0,0 +1,134 @@
+== WokeLang Standard Library
+
+A human-centered library collection for WokeLang, organized into common
+utilities and language-specific features.
+
+=== Structure
+
+....
+lib/
+├── common/ # Language-agnostic utilities
+│ ├── prelude.woke # Core utilities (identity, boolean, numeric, string, array)
+│ ├── collections.woke # Higher-order functions (map, filter, reduce)
+│ └── async.woke # Concurrent programming patterns
+│
+└── wokelang/ # WokeLang-specific features
+ ├── consent.woke # Consent and permission management
+ ├── emotes.woke # Emotional annotations and sentiment-aware code
+ └── gratitude.woke # Attribution and acknowledgment utilities
+....
+
+=== Common Library
+
+==== prelude.woke
+
+Core utilities that every program needs: - *Identity functions*:
+`+identity+`, `+constant+`, `+flip+` - *Boolean operations*: `+negate+`,
+`+allTrue+`, `+anyTrue+` - *Numeric utilities*: `+clamp+`, `+inRange+`,
+`+sign+`, `+isEven+`, `+isOdd+`, `+gcd+`, `+lcm+` - *String utilities*:
+`+isEmpty+`, `+repeat+`, `+startsWith+`, `+endsWith+` - *Array
+utilities*: `+head+`, `+tail+`, `+last+`, `+reverse+`, `+contains+`,
+`+indexOf+` - *Result utilities*: `+isOkay+`, `+isOops+`,
+`+getOrDefault+`, `+mapResult+` - *Debugging*: `+debug+`, `+assert+`
+
+==== collections.woke
+
+Higher-order functions for data transformation: - *Core
+transformations*: `+map+`, `+filter+`, `+reduce+`, `+reduceRight+` -
+*Searching*: `+find+`, `+findIndex+`, `+all+`, `+any+`, `+none+` -
+*Advanced transformations*: `+flatten+`, `+flatMap+`, `+zip+`,
+`+unzip+`, `+partition+`, `+groupBy+` - *Slicing*: `+take+`, `+drop+`,
+`+takeWhile+`, `+dropWhile+`, `+slice+` - *Statistics*: `+count+`,
+`+sum+`, `+product+`, `+average+` - *Sorting*: `+sortInts+` -
+*Deduplication*: `+unique+`, `+distinctBy+`
+
+==== async.woke
+
+Concurrent programming utilities: - *Worker patterns*: `+TaskRunner+`,
+parallel execution - *Promise-like patterns*: `+runAsync+`,
+`+parallel+`, `+race+` - *Retry patterns*: `+retry+`,
+`+retryWithBackoff+` - *Timeout patterns*: `+withTimeout+` -
+*Debounce/throttle*: `+debounce+` - *Channel utilities*:
+`+createChannel+`, `+channelSend+`, `+channelReceive+`
+
+=== WokeLang-Specific Library
+
+==== consent.woke
+
+Human-centered consent management: - *Safe execution*: `+withConsent+`,
+`+requireAllConsents+`, `+withAnyConsent+` - *Permission constants*:
+`+PERM_READ_FILE+`, `+PERM_NETWORK_HTTP+`, etc. - *Safe operations*:
+`+safeReadFile+`, `+safeWriteFile+`, `+safeHttpGet+` - *Audit logging*:
+`+logConsentRequest+`, `+createAuditTrail+` - *Privacy patterns*:
+`+withPrivacy+`, `+redact+`, `+anonymize+`
+
+==== emotes.woke
+
+Emotional annotations for code: - *Emote types*: `+Happy+`, `+Sad+`,
+`+Curious+`, `+Careful+`, `+Mindful+`, etc. - *Emote logging*:
+`+logWithEmote+` - *Sentiment-aware execution*: `+withCaution+`,
+`+withInvestigation+` - *Emotional state tracking*: `+EmotionalState+`,
+`+updateEmotionalState+` - *Code health indicators*:
+`+assessCodeHealth+`, `+reportCodeHealth+`
+
+==== gratitude.woke
+
+Attribution and acknowledgment: - *Gratitude registry*:
+`+createGratitudeRegistry+`, `+acknowledge+` - *Credit generation*:
+`+generateCredits+`, `+generateThankYouNote+` - *Dependency
+attribution*: `+acknowledgeDependency+`, `+generateLicenseNotices+` -
+*Contributor recognition*: `+recognizeContributor+` - *Gratitude
+expressions*: `+expressGratitude+`, `+randomGratitudeQuote+`
+
+=== Usage
+
+[source,woke]
+----
+use lib.common.prelude;
+use lib.common.collections;
+use lib.wokelang.consent;
+use lib.wokelang.emotes;
+
+to main() {
+ hello "Starting application";
+
+ (* Use common utilities *)
+ remember numbers = [1, 2, 3, 4, 5];
+ remember doubled = map(numbers, to (x: Int) -> Int { give back x * 2; });
+
+ (* Use consent-aware file reading *)
+ remember content = safeReadFile("config.json")?;
+
+ (* Log with emotional context *)
+ @happy(intensity=8)
+ logWithEmote(Proud(8), "Application started successfully!");
+
+ give back 0;
+ goodbye "Application complete";
+}
+----
+
+=== Philosophy
+
+The WokeLang standard library embodies the language’s core principles:
+
+[arabic]
+. *Human-Centered*: Every function is designed with human developers in
+mind
+. *Consent-First*: Sensitive operations require explicit permission
+. *Emotionally Aware*: Code can express and track emotional context
+. *Grateful*: Attribution and acknowledgment are first-class concepts
+
+=== Contributing
+
+When contributing to the library: 1. Include appropriate emote
+annotations 2. Add gratitude blocks acknowledging inspirations 3. Ensure
+consent is requested for sensitive operations 4. Write clear
+hello/goodbye lifecycle messages
+
+=== Gratitude
+
+This library was built with gratitude to: - Functional programming
+communities for inspiring composable patterns - Rust for Result types
+and error handling patterns - Go for channel-based concurrency - All
+contributors who help make WokeLang more human-centered
diff --git a/lib/README.md b/lib/README.md
deleted file mode 100644
index afe7ec7..0000000
--- a/lib/README.md
+++ /dev/null
@@ -1,132 +0,0 @@
-
-# WokeLang Standard Library
-
-A human-centered library collection for WokeLang, organized into common utilities
-and language-specific features.
-
-## Structure
-
-```
-lib/
-├── common/ # Language-agnostic utilities
-│ ├── prelude.woke # Core utilities (identity, boolean, numeric, string, array)
-│ ├── collections.woke # Higher-order functions (map, filter, reduce)
-│ └── async.woke # Concurrent programming patterns
-│
-└── wokelang/ # WokeLang-specific features
- ├── consent.woke # Consent and permission management
- ├── emotes.woke # Emotional annotations and sentiment-aware code
- └── gratitude.woke # Attribution and acknowledgment utilities
-```
-
-## Common Library
-
-### prelude.woke
-Core utilities that every program needs:
-- **Identity functions**: `identity`, `constant`, `flip`
-- **Boolean operations**: `negate`, `allTrue`, `anyTrue`
-- **Numeric utilities**: `clamp`, `inRange`, `sign`, `isEven`, `isOdd`, `gcd`, `lcm`
-- **String utilities**: `isEmpty`, `repeat`, `startsWith`, `endsWith`
-- **Array utilities**: `head`, `tail`, `last`, `reverse`, `contains`, `indexOf`
-- **Result utilities**: `isOkay`, `isOops`, `getOrDefault`, `mapResult`
-- **Debugging**: `debug`, `assert`
-
-### collections.woke
-Higher-order functions for data transformation:
-- **Core transformations**: `map`, `filter`, `reduce`, `reduceRight`
-- **Searching**: `find`, `findIndex`, `all`, `any`, `none`
-- **Advanced transformations**: `flatten`, `flatMap`, `zip`, `unzip`, `partition`, `groupBy`
-- **Slicing**: `take`, `drop`, `takeWhile`, `dropWhile`, `slice`
-- **Statistics**: `count`, `sum`, `product`, `average`
-- **Sorting**: `sortInts`
-- **Deduplication**: `unique`, `distinctBy`
-
-### async.woke
-Concurrent programming utilities:
-- **Worker patterns**: `TaskRunner`, parallel execution
-- **Promise-like patterns**: `runAsync`, `parallel`, `race`
-- **Retry patterns**: `retry`, `retryWithBackoff`
-- **Timeout patterns**: `withTimeout`
-- **Debounce/throttle**: `debounce`
-- **Channel utilities**: `createChannel`, `channelSend`, `channelReceive`
-
-## WokeLang-Specific Library
-
-### consent.woke
-Human-centered consent management:
-- **Safe execution**: `withConsent`, `requireAllConsents`, `withAnyConsent`
-- **Permission constants**: `PERM_READ_FILE`, `PERM_NETWORK_HTTP`, etc.
-- **Safe operations**: `safeReadFile`, `safeWriteFile`, `safeHttpGet`
-- **Audit logging**: `logConsentRequest`, `createAuditTrail`
-- **Privacy patterns**: `withPrivacy`, `redact`, `anonymize`
-
-### emotes.woke
-Emotional annotations for code:
-- **Emote types**: `Happy`, `Sad`, `Curious`, `Careful`, `Mindful`, etc.
-- **Emote logging**: `logWithEmote`
-- **Sentiment-aware execution**: `withCaution`, `withInvestigation`
-- **Emotional state tracking**: `EmotionalState`, `updateEmotionalState`
-- **Code health indicators**: `assessCodeHealth`, `reportCodeHealth`
-
-### gratitude.woke
-Attribution and acknowledgment:
-- **Gratitude registry**: `createGratitudeRegistry`, `acknowledge`
-- **Credit generation**: `generateCredits`, `generateThankYouNote`
-- **Dependency attribution**: `acknowledgeDependency`, `generateLicenseNotices`
-- **Contributor recognition**: `recognizeContributor`
-- **Gratitude expressions**: `expressGratitude`, `randomGratitudeQuote`
-
-## Usage
-
-```woke
-use lib.common.prelude;
-use lib.common.collections;
-use lib.wokelang.consent;
-use lib.wokelang.emotes;
-
-to main() {
- hello "Starting application";
-
- (* Use common utilities *)
- remember numbers = [1, 2, 3, 4, 5];
- remember doubled = map(numbers, to (x: Int) -> Int { give back x * 2; });
-
- (* Use consent-aware file reading *)
- remember content = safeReadFile("config.json")?;
-
- (* Log with emotional context *)
- @happy(intensity=8)
- logWithEmote(Proud(8), "Application started successfully!");
-
- give back 0;
- goodbye "Application complete";
-}
-```
-
-## Philosophy
-
-The WokeLang standard library embodies the language's core principles:
-
-1. **Human-Centered**: Every function is designed with human developers in mind
-2. **Consent-First**: Sensitive operations require explicit permission
-3. **Emotionally Aware**: Code can express and track emotional context
-4. **Grateful**: Attribution and acknowledgment are first-class concepts
-
-## Contributing
-
-When contributing to the library:
-1. Include appropriate emote annotations
-2. Add gratitude blocks acknowledging inspirations
-3. Ensure consent is requested for sensitive operations
-4. Write clear hello/goodbye lifecycle messages
-
-## Gratitude
-
-This library was built with gratitude to:
-- Functional programming communities for inspiring composable patterns
-- Rust for Result types and error handling patterns
-- Go for channel-based concurrency
-- All contributors who help make WokeLang more human-centered
diff --git a/lib/common/README.adoc b/lib/common/README.adoc
new file mode 100644
index 0000000..2805c63
--- /dev/null
+++ b/lib/common/README.adoc
@@ -0,0 +1,86 @@
+== WokeLang Common Library
+
+This directory contains WokeLang’s implementation of the
+*aggregate-library* common operations, plus additional utilities that
+are language-agnostic.
+
+=== Relationship to aggregate-library
+
+The
+https://github.com/hyperpolymath/aggregate-library[aggregate-library]
+defines 20 core operations that work across all seven languages in the
+ecosystem. WokeLang implements all of these operations.
+
+==== Core Operations (from aggregate-library)
+
+[width="100%",cols="46%,54%",options="header",]
+|===
+|Category |Operations
+|Arithmetic (5) |`+add+`, `+subtract+`, `+multiply+`, `+divide+`,
+`+modulo+`
+
+|Comparison (6) |`+less_than+`, `+greater_than+`, `+equal+`,
+`+not_equal+`, `+less_equal+`, `+greater_equal+`
+
+|Logical (3) |`+logical_and+`, `+logical_or+`, `+logical_not+`
+
+|String (3) |`+concat+`, `+string_length+`, `+substring+`
+
+|Collection (4) |`+map+`, `+filter+`, `+fold+`, `+contains+`
+
+|Conditional (1) |`+if_then_else+`
+|===
+
+==== Extended Utilities (WokeLang common extensions)
+
+Beyond the 20 core operations, this directory includes additional
+language-agnostic utilities:
+
+* *prelude.woke* - Identity functions, numeric utilities, array helpers,
+Result utilities
+* *collections.woke* - Extended collection operations (zip, partition,
+groupBy, etc.)
+* *async.woke* - Concurrent programming patterns (workers, retry,
+timeout)
+
+=== Usage
+
+[source,woke]
+----
+(* Import common library *)
+use lib.common.prelude;
+use lib.common.collections;
+
+to main() {
+ (* Use core operations *)
+ remember sum = add(10, 20);
+ remember doubled = map([1, 2, 3], to (x: Int) -> Int { give back multiply(x, 2); });
+
+ (* Use extended utilities *)
+ remember evens = filter(doubled, isEven);
+
+ give back sum;
+}
+----
+
+=== Files
+
+[cols=",",options="header",]
+|===
+|File |Description
+|`+core.woke+` |The 20 aggregate-library operations
+|`+prelude.woke+` |Extended core utilities
+|`+collections.woke+` |Extended collection operations
+|`+async.woke+` |Concurrent programming utilities
+|===
+
+=== Specification Compliance
+
+All implementations in `+core.woke+` comply with the aggregate-library
+specifications and pass the defined test cases.
+
+=== See Also
+
+* https://github.com/hyperpolymath/aggregate-library[aggregate-library
+specifications]
+* link:../wokelang/README.md[WokeLang-specific library]
diff --git a/lib/common/README.md b/lib/common/README.md
deleted file mode 100644
index 9f92184..0000000
--- a/lib/common/README.md
+++ /dev/null
@@ -1,67 +0,0 @@
-
-# WokeLang Common Library
-
-This directory contains WokeLang's implementation of the **aggregate-library** common operations, plus additional utilities that are language-agnostic.
-
-## Relationship to aggregate-library
-
-The [aggregate-library](https://github.com/hyperpolymath/aggregate-library) defines 20 core operations that work across all seven languages in the ecosystem. WokeLang implements all of these operations.
-
-### Core Operations (from aggregate-library)
-
-| Category | Operations |
-|----------|------------|
-| Arithmetic (5) | `add`, `subtract`, `multiply`, `divide`, `modulo` |
-| Comparison (6) | `less_than`, `greater_than`, `equal`, `not_equal`, `less_equal`, `greater_equal` |
-| Logical (3) | `logical_and`, `logical_or`, `logical_not` |
-| String (3) | `concat`, `string_length`, `substring` |
-| Collection (4) | `map`, `filter`, `fold`, `contains` |
-| Conditional (1) | `if_then_else` |
-
-### Extended Utilities (WokeLang common extensions)
-
-Beyond the 20 core operations, this directory includes additional language-agnostic utilities:
-
-- **prelude.woke** - Identity functions, numeric utilities, array helpers, Result utilities
-- **collections.woke** - Extended collection operations (zip, partition, groupBy, etc.)
-- **async.woke** - Concurrent programming patterns (workers, retry, timeout)
-
-## Usage
-
-```woke
-(* Import common library *)
-use lib.common.prelude;
-use lib.common.collections;
-
-to main() {
- (* Use core operations *)
- remember sum = add(10, 20);
- remember doubled = map([1, 2, 3], to (x: Int) -> Int { give back multiply(x, 2); });
-
- (* Use extended utilities *)
- remember evens = filter(doubled, isEven);
-
- give back sum;
-}
-```
-
-## Files
-
-| File | Description |
-|------|-------------|
-| `core.woke` | The 20 aggregate-library operations |
-| `prelude.woke` | Extended core utilities |
-| `collections.woke` | Extended collection operations |
-| `async.woke` | Concurrent programming utilities |
-
-## Specification Compliance
-
-All implementations in `core.woke` comply with the aggregate-library specifications and pass the defined test cases.
-
-## See Also
-
-- [aggregate-library specifications](https://github.com/hyperpolymath/aggregate-library)
-- [WokeLang-specific library](../wokelang/README.md)
diff --git a/lib/wokelang/README.adoc b/lib/wokelang/README.adoc
new file mode 100644
index 0000000..4f3a7c5
--- /dev/null
+++ b/lib/wokelang/README.adoc
@@ -0,0 +1,107 @@
+== WokeLang-Specific Library
+
+This directory contains libraries that are *unique to WokeLang* and
+represent the language’s distinctive features. These are NOT part of the
+common aggregate-library.
+
+=== What Makes WokeLang Unique
+
+WokeLang is a *human-centered, consent-driven programming language* with
+features not found in the other six languages in the ecosystem:
+
+[arabic]
+. *Consent-First Design* - Sensitive operations require explicit user
+permission
+. *Emotional Annotations* - Code can express and track emotional context
+. *Gratitude as Code* - Attribution and acknowledgment are first-class
+constructs
+. *Hello/Goodbye Lifecycle* - Functions can declare entry/exit messages
+
+=== Library Modules
+
+==== consent.woke
+
+Permission and consent management for sensitive operations: -
+`+withConsent(permission, reason, action)+` - Execute action only with
+consent - `+requireAllConsents(permissions, action)+` - Require multiple
+permissions - `+safeReadFile(path)+`, `+safeWriteFile(path, content)+` -
+Consent-protected I/O - `+redact(text, patterns)+`, `+anonymize(data)+`
+- Privacy utilities - Permission constants: `+PERM_READ_FILE+`,
+`+PERM_NETWORK_HTTP+`, etc.
+
+==== emotes.woke
+
+Emotional annotations and sentiment-aware programming: - Emote types:
+`+Happy+`, `+Sad+`, `+Curious+`, `+Careful+`, `+Mindful+`,
+`+Thoughtful+`, etc. - `+logWithEmote(emote, message)+` - Emotion-aware
+logging - `+withCaution(level, action)+` - Sentiment-controlled
+execution - `+EmotionalState+` tracking and `+CodeHealth+` assessment
+
+==== gratitude.woke
+
+Attribution and acknowledgment utilities: - `+GratitudeRegistry+` for
+managing acknowledgments - `+generateCredits(registry)+` - Create
+attribution text - `+acknowledgeDependency(...)+` - Track third-party
+dependencies - `+recognizeContributor(contributor)+` - Spotlight
+contributors
+
+=== Usage
+
+[source,woke]
+----
+use lib.wokelang.consent;
+use lib.wokelang.emotes;
+use lib.wokelang.gratitude;
+
+@mindful(importance=8)
+to main() {
+ hello "Starting application";
+
+ (* Use consent-protected file reading *)
+ remember config = safeReadFile("config.json")?;
+
+ (* Log with emotional context *)
+ logWithEmote(Happy(7), "Configuration loaded successfully!");
+
+ (* Execute with caution for risky operations *)
+ remember result = withCaution(5, to () -> Result[Data, String] {
+ give back processData(config);
+ });
+
+ give back 0;
+
+ goodbye "Application complete";
+}
+
+thanks to {
+ "WokeLang Community" → "Building human-centered software";
+}
+----
+
+=== What’s NOT Here
+
+The following belong in `+lib/common/+` as they’re shared across all
+seven languages: - Basic arithmetic (`+add+`, `+subtract+`,
+`+multiply+`, `+divide+`, `+modulo+`) - Comparisons (`+less_than+`,
+`+greater_than+`, `+equal+`, etc.) - Logical operations (`+and+`,
+`+or+`, `+not+`) - String operations (`+concat+`, `+length+`,
+`+substring+`) - Collection operations (`+map+`, `+filter+`, `+fold+`,
+`+contains+`) - Conditional (`+if_then_else+`)
+
+=== Philosophy
+
+____
+"`Code should be written for humans first, machines second.`"
+____
+
+WokeLang’s specific library embodies this philosophy by providing: -
+*Consent* - Respecting user autonomy and privacy - *Emotion* -
+Acknowledging the human side of programming - *Gratitude* - Celebrating
+contributions and collaboration
+
+=== See Also
+
+* link:../common/README.md[Common Library] - Shared operations from
+aggregate-library
+* https://github.com/hyperpolymath/aggregate-library[aggregate-library]
+- The cross-language specification
diff --git a/lib/wokelang/README.md b/lib/wokelang/README.md
deleted file mode 100644
index 0181d94..0000000
--- a/lib/wokelang/README.md
+++ /dev/null
@@ -1,96 +0,0 @@
-
-# WokeLang-Specific Library
-
-This directory contains libraries that are **unique to WokeLang** and represent the language's distinctive features. These are NOT part of the common aggregate-library.
-
-## What Makes WokeLang Unique
-
-WokeLang is a **human-centered, consent-driven programming language** with features not found in the other six languages in the ecosystem:
-
-1. **Consent-First Design** - Sensitive operations require explicit user permission
-2. **Emotional Annotations** - Code can express and track emotional context
-3. **Gratitude as Code** - Attribution and acknowledgment are first-class constructs
-4. **Hello/Goodbye Lifecycle** - Functions can declare entry/exit messages
-
-## Library Modules
-
-### consent.woke
-Permission and consent management for sensitive operations:
-- `withConsent(permission, reason, action)` - Execute action only with consent
-- `requireAllConsents(permissions, action)` - Require multiple permissions
-- `safeReadFile(path)`, `safeWriteFile(path, content)` - Consent-protected I/O
-- `redact(text, patterns)`, `anonymize(data)` - Privacy utilities
-- Permission constants: `PERM_READ_FILE`, `PERM_NETWORK_HTTP`, etc.
-
-### emotes.woke
-Emotional annotations and sentiment-aware programming:
-- Emote types: `Happy`, `Sad`, `Curious`, `Careful`, `Mindful`, `Thoughtful`, etc.
-- `logWithEmote(emote, message)` - Emotion-aware logging
-- `withCaution(level, action)` - Sentiment-controlled execution
-- `EmotionalState` tracking and `CodeHealth` assessment
-
-### gratitude.woke
-Attribution and acknowledgment utilities:
-- `GratitudeRegistry` for managing acknowledgments
-- `generateCredits(registry)` - Create attribution text
-- `acknowledgeDependency(...)` - Track third-party dependencies
-- `recognizeContributor(contributor)` - Spotlight contributors
-
-## Usage
-
-```woke
-use lib.wokelang.consent;
-use lib.wokelang.emotes;
-use lib.wokelang.gratitude;
-
-@mindful(importance=8)
-to main() {
- hello "Starting application";
-
- (* Use consent-protected file reading *)
- remember config = safeReadFile("config.json")?;
-
- (* Log with emotional context *)
- logWithEmote(Happy(7), "Configuration loaded successfully!");
-
- (* Execute with caution for risky operations *)
- remember result = withCaution(5, to () -> Result[Data, String] {
- give back processData(config);
- });
-
- give back 0;
-
- goodbye "Application complete";
-}
-
-thanks to {
- "WokeLang Community" → "Building human-centered software";
-}
-```
-
-## What's NOT Here
-
-The following belong in `lib/common/` as they're shared across all seven languages:
-- Basic arithmetic (`add`, `subtract`, `multiply`, `divide`, `modulo`)
-- Comparisons (`less_than`, `greater_than`, `equal`, etc.)
-- Logical operations (`and`, `or`, `not`)
-- String operations (`concat`, `length`, `substring`)
-- Collection operations (`map`, `filter`, `fold`, `contains`)
-- Conditional (`if_then_else`)
-
-## Philosophy
-
-> "Code should be written for humans first, machines second."
-
-WokeLang's specific library embodies this philosophy by providing:
-- **Consent** - Respecting user autonomy and privacy
-- **Emotion** - Acknowledging the human side of programming
-- **Gratitude** - Celebrating contributions and collaboration
-
-## See Also
-
-- [Common Library](../common/README.md) - Shared operations from aggregate-library
-- [aggregate-library](https://github.com/hyperpolymath/aggregate-library) - The cross-language specification
diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc
new file mode 100644
index 0000000..6ac9744
--- /dev/null
+++ b/llm-warmup-dev.adoc
@@ -0,0 +1,19 @@
+== LLM Warmup — wokelang (Developer)
+
+=== What is wokelang?
+
+See README.adoc for overview.
+
+=== Key Commands
+
+* `+just setup+` — set up development environment
+* `+just build+` — build the project
+* `+just test+` — run tests
+* `+just doctor+` — diagnose issues
+* `+just heal+` — attempt auto-repair
+
+=== Quick Context
+
+* License: MPL-2.0
+* Part of hyperpolymath ecosystem
+* See EXPLAINME.adoc for architecture
diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md
deleted file mode 100644
index 117f83b..0000000
--- a/llm-warmup-dev.md
+++ /dev/null
@@ -1,20 +0,0 @@
-
-# LLM Warmup — wokelang (Developer)
-
-## What is wokelang?
-See README.adoc for overview.
-
-## Key Commands
-- `just setup` — set up development environment
-- `just build` — build the project
-- `just test` — run tests
-- `just doctor` — diagnose issues
-- `just heal` — attempt auto-repair
-
-## Quick Context
-- License: MPL-2.0
-- Part of hyperpolymath ecosystem
-- See EXPLAINME.adoc for architecture
diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc
new file mode 100644
index 0000000..17641f0
--- /dev/null
+++ b/llm-warmup-user.adoc
@@ -0,0 +1,19 @@
+== LLM Warmup — wokelang (User)
+
+=== What is wokelang?
+
+See README.adoc for overview.
+
+=== Key Commands
+
+* `+just setup+` — set up development environment
+* `+just build+` — build the project
+* `+just test+` — run tests
+* `+just doctor+` — diagnose issues
+* `+just heal+` — attempt auto-repair
+
+=== Quick Context
+
+* License: MPL-2.0
+* Part of hyperpolymath ecosystem
+* See EXPLAINME.adoc for architecture
diff --git a/llm-warmup-user.md b/llm-warmup-user.md
deleted file mode 100644
index 5f908e6..0000000
--- a/llm-warmup-user.md
+++ /dev/null
@@ -1,20 +0,0 @@
-
-# LLM Warmup — wokelang (User)
-
-## What is wokelang?
-See README.adoc for overview.
-
-## Key Commands
-- `just setup` — set up development environment
-- `just build` — build the project
-- `just test` — run tests
-- `just doctor` — diagnose issues
-- `just heal` — attempt auto-repair
-
-## Quick Context
-- License: MPL-2.0
-- Part of hyperpolymath ecosystem
-- See EXPLAINME.adoc for architecture
diff --git a/site/index.adoc b/site/index.adoc
new file mode 100644
index 0000000..d19e17f
--- /dev/null
+++ b/site/index.adoc
@@ -0,0 +1,28 @@
+== // SPDX-License-Identifier: CC-BY-SA-4.0
+
+title: WokeLang date: 2026-03-31 —
+
+== WokeLang
+
+The public web home for this project is
+https://wokelang.org[wokelang.org].
+
+WokeLang: A Human-Centered Programming Language
+
+WokeLang is a programming language designed for human collaboration,
+empathy, and safety—without sacrificing power or performance. It
+combines:
+
+=== Project Links
+
+* Website: https://wokelang.org[wokelang.org]
+* Source: https://github.com/hyperpolymath/wokelang
+* README:
+https://github.com/hyperpolymath/wokelang/blob/main/README.adoc[project
+overview]
+* Docs:
+https://github.com/hyperpolymath/wokelang/tree/main/docs[documentation
+directory]
+
+This page is a lightweight landing point for the repository and will
+grow with the project.
diff --git a/site/index.md b/site/index.md
deleted file mode 100644
index ce6a82c..0000000
--- a/site/index.md
+++ /dev/null
@@ -1,26 +0,0 @@
-
-// SPDX-License-Identifier: CC-BY-SA-4.0
----
-title: WokeLang
-date: 2026-03-31
----
-
-# WokeLang
-
-The public web home for this project is [wokelang.org](https://wokelang.org).
-
-WokeLang: A Human-Centered Programming Language
-
-WokeLang is a programming language designed for human collaboration, empathy, and safety—without sacrificing power or performance. It combines:
-
-## Project Links
-
-- Website: [wokelang.org](https://wokelang.org)
-- Source: [https://github.com/hyperpolymath/wokelang](https://github.com/hyperpolymath/wokelang)
-- README: [project overview](https://github.com/hyperpolymath/wokelang/blob/main/README.adoc)
-- Docs: [documentation directory](https://github.com/hyperpolymath/wokelang/tree/main/docs)
-
-This page is a lightweight landing point for the repository and will grow with the project.
diff --git a/spec/axiomatic-semantics.md b/spec/axiomatic-semantics.adoc
similarity index 75%
rename from spec/axiomatic-semantics.md
rename to spec/axiomatic-semantics.adoc
index b09e3a1..1f0ec5e 100644
--- a/spec/axiomatic-semantics.md
+++ b/spec/axiomatic-semantics.adoc
@@ -1,39 +1,35 @@
-
-# SPDX-License-Identifier: CC-BY-SA-4.0
-# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+== SPDX-License-Identifier: CC-BY-SA-4.0
-# WokeLang Axiomatic Semantics: Consent Preconditions
+== Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) j.d.a.jewell@open.ac.uk
-**Version:** 1.0.0
-**Date:** 2026-03-14
+== WokeLang Axiomatic Semantics: Consent Preconditions
----
+*Version:* 1.0.0 *Date:* 2026-03-14
-## 1. Overview
+'''''
-WokeLang's axiomatic semantics extend Hoare logic with *consent preconditions*
-— formal requirements that certain operations may only proceed if explicit
-user consent has been obtained. This ensures that WokeLang programs cannot
-perform sensitive operations silently.
+=== 1. Overview
-### 1.1 Consent Hoare Triple
+WokeLang’s axiomatic semantics extend Hoare logic with _consent
+preconditions_ — formal requirements that certain operations may only
+proceed if explicit user consent has been obtained. This ensures that
+WokeLang programs cannot perform sensitive operations silently.
-```
+==== 1.1 Consent Hoare Triple
+
+....
{P, C} S {Q, C'}
where C ⊆ ConsentSet is the set of active consents
-```
+....
----
+'''''
-## 2. Consent Axioms
+=== 2. Consent Axioms
-### 2.1 Consent Gate
+==== 2.1 Consent Gate
-```
+....
prompt ∉ C user grants consent
──────────────────────────────────────────────────────── [Consent-Grant]
{P, C} only if okay "prompt" { S } {Q, C ∪ {prompt}}
@@ -42,59 +38,60 @@ where C ⊆ ConsentSet is the set of active consents
──────────────────────────────────────────────────── [Consent-Deny]
{P, C} only if okay "prompt" { S } {P, C}
(body S is not executed; program continues)
-```
+....
-### 2.2 Consent Propagation
+==== 2.2 Consent Propagation
-```
+....
prompt ∈ C (consent already granted)
────────────────────────────────────────────────── [Consent-Cached]
{P, C} only if okay "prompt" { S } {Q, C}
(body executes without re-prompting)
-```
+....
-### 2.3 Consent Requirement
+==== 2.3 Consent Requirement
Operations that access external resources require consent:
-```
+....
requires_consent(op) = true "access" ∉ C
────────────────────────────────────────────────────── [Consent-Required]
{P, C} op {⊥} (error: consent not obtained)
-```
+....
----
+'''''
-## 3. Gratitude Axioms
+=== 3. Gratitude Axioms
-### 3.1 Attribution Preservation
+==== 3.1 Attribution Preservation
-```
+....
────────────────────────────────────────────────────────── [Grat-Preserve]
{true, C} thanks to { entries } {gratitude_table updated, C}
(gratitude declarations are pure metadata — no side effects)
-```
+....
-### 3.2 Gratitude Completeness
+==== 3.2 Gratitude Completeness
-**Axiom:** Every function using external code should have a corresponding
-`thanks to` block. This is a convention, not enforced by the type system.
+*Axiom:* Every function using external code should have a corresponding
+`+thanks to+` block. This is a convention, not enforced by the type
+system.
----
+'''''
-## 4. Worker Axioms
+=== 4. Worker Axioms
-### 4.1 Worker Isolation
+==== 4.1 Worker Isolation
-```
+....
────────────────────────────────────────────────────── [W-Isolate]
{P, C} spawn worker W {Q ∧ ρ_W ∩ ρ_parent = ∅, C}
(workers have their own isolated environment)
-```
+....
-### 4.2 Channel Safety
+==== 4.2 Channel Safety
-```
+....
channel(ch) open value : τ
──────────────────────────────────────── [W-Send]
{channel_open(ch), C} send value to ch {message_queued, C}
@@ -106,11 +103,11 @@ Operations that access external resources require consent:
channel(ch) empty (blocking semantics)
────────────────────────────────────────────── [W-Recv-Block]
{¬message_available(ch), C} receive from ch {blocks until message, C}
-```
+....
-### 4.3 Worker Lifecycle
+==== 4.3 Worker Lifecycle
-```
+....
W running
────────────────────────────────── [W-Cancel]
{worker_alive(W), C} cancel W {worker_cancelled(W), C}
@@ -118,15 +115,15 @@ Operations that access external resources require consent:
W running
────────────────────────────────── [W-Await]
{worker_alive(W), C} await W {worker_completed(W), C}
-```
+....
----
+'''''
-## 5. Error Handling Axioms
+=== 5. Error Handling Axioms
-### 5.1 Attempt Block
+==== 5.1 Attempt Block
-```
+....
{P, C} S {Q, C} (S succeeds)
────────────────────────────────────────────────────────── [Err-Success]
{P, C} attempt safely { S } or reassure msg {Q, C}
@@ -135,20 +132,20 @@ Operations that access external resources require consent:
────────────────────────────────────────────────────────── [Err-Reassure]
{P, C} attempt safely { S } or reassure msg {error handled, C}
(msg displayed; execution continues)
-```
+....
-### 5.2 Complain
+==== 5.2 Complain
-```
+....
────────────────────────────────────────────── [Err-Complain]
{true, C} complain msg {⊥} (error raised)
-```
+....
----
+'''''
-## 6. Result Type Axioms
+=== 6. Result Type Axioms
-```
+....
────────────────────────────────────────── [Res-Okay]
{true, C} Okay(v) {result = Ok(v), C}
@@ -162,43 +159,43 @@ Operations that access external resources require consent:
result = Err(e)
────────────────────────────────────────── [Res-Unwrap-Err]
{result = Err(e), C} unwrap result {⊥}
-```
+....
----
+'''''
-## 7. Pragma Axioms
+=== 7. Pragma Axioms
-```
+....
────────────────────────────────────────────────────── [Pragma-Care]
{true, C} #care on {extra_validation = true, C}
(enables additional safety checks)
────────────────────────────────────────────────────── [Pragma-Strict]
{true, C} #strict on {warnings_are_errors = true, C}
-```
+....
----
+'''''
-## 8. Key Theorems
+=== 8. Key Theorems
-### 8.1 Consent Safety
+==== 8.1 Consent Safety
-**Theorem:** No operation requiring consent can execute without explicit
+*Theorem:* No operation requiring consent can execute without explicit
consent in the consent set C. The consent gate is the only way to add
elements to C.
-### 8.2 Worker Isolation
+==== 8.2 Worker Isolation
-**Theorem:** Workers cannot access the parent environment's mutable state.
+*Theorem:* Workers cannot access the parent environment’s mutable state.
Communication is exclusively through channels (message passing).
-### 8.3 Gentle Error Handling
+==== 8.3 Gentle Error Handling
-**Theorem:** An `attempt safely` block never causes program termination.
+*Theorem:* An `+attempt safely+` block never causes program termination.
All errors within the block are caught and the reassurance message is
displayed.
-### 8.4 Consent Monotonicity
+==== 8.4 Consent Monotonicity
-**Theorem:** The consent set C only grows during execution (consents are
-never revoked within a session): `{P, C} S {Q, C'} ⟹ C ⊆ C'`.
+*Theorem:* The consent set C only grows during execution (consents are
+never revoked within a session): `+{P, C} S {Q, C'} ⟹ C ⊆ C'+`.
diff --git a/spec/system-specs.adoc b/spec/system-specs.adoc
new file mode 100644
index 0000000..2d092db
--- /dev/null
+++ b/spec/system-specs.adoc
@@ -0,0 +1,96 @@
+== SPDX-License-Identifier: CC-BY-SA-4.0
+
+== Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) j.d.a.jewell@open.ac.uk
+
+== WokeLang — System Specifications
+
+WokeLang is an interpreted language with a Rust interpreter and OCaml
+parser, featuring consent-based programming and social-justice-informed
+semantics.
+
+=== Memory Model
+
+WokeLang uses a hybrid memory model suited to its interpreter
+architecture:
+
+* *Single-thread environments*: Values are stored in environments using
+`+Rc>+` (reference-counted, interior-mutable cells). This
+avoids the overhead of atomic operations when concurrency is not needed.
+* *Worker environments*: When workers are spawned, environments switch
+to `+Arc>+` for thread-safe shared access. Each worker receives
+an isolated copy of its captured environment at spawn time.
+* *Value semantics*: Primitive values (numbers, booleans, strings) are
+cloned on assignment. Compound values (lists, maps) use reference
+counting with copy-on-write where applicable.
+* *No garbage collector*: Memory is reclaimed through reference
+counting. Cycle detection is not currently implemented; cyclic
+structures will leak.
+* *Stack frames*: Function calls push frames onto an explicit call stack
+in the interpreter. Each frame holds local bindings as a HashMap.
+* *Environment chains*: Lexical scoping is implemented via linked
+environment chains. Each scope holds a reference to its parent scope.
+
+=== Concurrency Model
+
+WokeLang provides several concurrency primitives:
+
+* *Workers*: Spawned via dedicated syntax, workers run on OS threads
+(`+std::thread::spawn+`). Each worker receives an isolated copy of its
+environment, preventing shared mutable state between workers.
+* *Channels*: Go-style communication channels built on Rust’s `+mpsc+`
+(multi-producer, single-consumer). Workers communicate by sending and
+receiving values through named channels.
+* *Side quests*: Lightweight background tasks that run concurrently with
+the main program. Side quests have lower priority than the main thread
+and report results asynchronously.
+* *Superpowers*: Elevated execution contexts that can bypass normal
+consent checks for system-level operations. Superpowers run in isolated
+sandboxes with explicit capability grants.
+* *No shared memory*: Workers cannot access each other’s environments.
+All inter-worker communication goes through channels, preventing data
+races by design.
+* *Join semantics*: The main thread can wait for workers to complete and
+collect their return values.
+
+=== Effect System
+
+WokeLang’s effect system is built around the consent model:
+
+* *Consent system*: The primary effect-management mechanism. Operations
+that affect state, perform IO, or access sensitive resources require
+explicit consent through `+only if okay+` gates.
+* *`+only if okay+` gates*: Before performing a side effect, the runtime
+checks whether consent has been granted for that category of effect.
+Unconsented effects are blocked at runtime.
+* *Effect categories*: Effects are classified into categories (IO,
+network, file system, environment access). Consent is granted
+per-category.
+* *Consent propagation*: When a function calls another function, consent
+context propagates through the call chain. Inner functions cannot
+escalate beyond the consent granted to their callers.
+* *Monotonic consent*: Consent is monotonic within a session — once
+granted, it only grows and is never revoked during execution. New
+consent categories can be added but existing grants persist until
+session end.
+* *Audit trail*: All consent checks are logged, providing a runtime
+trace of which effects were attempted and whether they were permitted.
+
+=== Module System
+
+WokeLang uses a straightforward import/export model:
+
+* *`+use+` imports*: Modules are imported with the `+use+` keyword.
+Specific bindings can be selected and optionally renamed with the
+`+renamed+` keyword: `+use math (sqrt, pow renamed power)+`.
+* *`+share+` exports*: Public bindings are explicitly exported with the
+`+share+` keyword. Only shared bindings are visible to importing
+modules.
+* *File-based modules*: Each source file is a module. The module name is
+derived from the file path relative to the project root.
+* *Namespace isolation*: Imported names do not pollute the global scope.
+They are scoped to the importing module unless explicitly re-shared.
+* *Circular dependency detection*: The module loader detects circular
+imports and raises an error at load time rather than entering infinite
+recursion.
+* *No package manager yet*: Dependencies are managed manually via file
+paths. A package ecosystem is planned for future releases.
diff --git a/spec/system-specs.md b/spec/system-specs.md
deleted file mode 100644
index f0db143..0000000
--- a/spec/system-specs.md
+++ /dev/null
@@ -1,91 +0,0 @@
-
-# SPDX-License-Identifier: CC-BY-SA-4.0
-# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
-
-# WokeLang — System Specifications
-
-WokeLang is an interpreted language with a Rust interpreter and OCaml parser,
-featuring consent-based programming and social-justice-informed semantics.
-
-## Memory Model
-
-WokeLang uses a hybrid memory model suited to its interpreter architecture:
-
-- **Single-thread environments**: Values are stored in environments using
- `Rc>` (reference-counted, interior-mutable cells). This avoids the
- overhead of atomic operations when concurrency is not needed.
-- **Worker environments**: When workers are spawned, environments switch to
- `Arc>` for thread-safe shared access. Each worker receives an isolated
- copy of its captured environment at spawn time.
-- **Value semantics**: Primitive values (numbers, booleans, strings) are cloned on
- assignment. Compound values (lists, maps) use reference counting with
- copy-on-write where applicable.
-- **No garbage collector**: Memory is reclaimed through reference counting. Cycle
- detection is not currently implemented; cyclic structures will leak.
-- **Stack frames**: Function calls push frames onto an explicit call stack in the
- interpreter. Each frame holds local bindings as a HashMap.
-- **Environment chains**: Lexical scoping is implemented via linked environment
- chains. Each scope holds a reference to its parent scope.
-
-## Concurrency Model
-
-WokeLang provides several concurrency primitives:
-
-- **Workers**: Spawned via dedicated syntax, workers run on OS threads
- (`std::thread::spawn`). Each worker receives an isolated copy of its environment,
- preventing shared mutable state between workers.
-- **Channels**: Go-style communication channels built on Rust's `mpsc`
- (multi-producer, single-consumer). Workers communicate by sending and receiving
- values through named channels.
-- **Side quests**: Lightweight background tasks that run concurrently with the main
- program. Side quests have lower priority than the main thread and report results
- asynchronously.
-- **Superpowers**: Elevated execution contexts that can bypass normal consent checks
- for system-level operations. Superpowers run in isolated sandboxes with explicit
- capability grants.
-- **No shared memory**: Workers cannot access each other's environments. All
- inter-worker communication goes through channels, preventing data races by design.
-- **Join semantics**: The main thread can wait for workers to complete and collect
- their return values.
-
-## Effect System
-
-WokeLang's effect system is built around the consent model:
-
-- **Consent system**: The primary effect-management mechanism. Operations that
- affect state, perform IO, or access sensitive resources require explicit consent
- through `only if okay` gates.
-- **`only if okay` gates**: Before performing a side effect, the runtime checks
- whether consent has been granted for that category of effect. Unconsented effects
- are blocked at runtime.
-- **Effect categories**: Effects are classified into categories (IO, network, file
- system, environment access). Consent is granted per-category.
-- **Consent propagation**: When a function calls another function, consent context
- propagates through the call chain. Inner functions cannot escalate beyond the
- consent granted to their callers.
-- **Monotonic consent**: Consent is monotonic within a session — once granted,
- it only grows and is never revoked during execution. New consent categories
- can be added but existing grants persist until session end.
-- **Audit trail**: All consent checks are logged, providing a runtime trace of
- which effects were attempted and whether they were permitted.
-
-## Module System
-
-WokeLang uses a straightforward import/export model:
-
-- **`use` imports**: Modules are imported with the `use` keyword. Specific bindings
- can be selected and optionally renamed with the `renamed` keyword:
- `use math (sqrt, pow renamed power)`.
-- **`share` exports**: Public bindings are explicitly exported with the `share`
- keyword. Only shared bindings are visible to importing modules.
-- **File-based modules**: Each source file is a module. The module name is derived
- from the file path relative to the project root.
-- **Namespace isolation**: Imported names do not pollute the global scope. They are
- scoped to the importing module unless explicitly re-shared.
-- **Circular dependency detection**: The module loader detects circular imports and
- raises an error at load time rather than entering infinite recursion.
-- **No package manager yet**: Dependencies are managed manually via file paths.
- A package ecosystem is planned for future releases.