Skip to content

Commit 3d473c6

Browse files
claudehyperpolymath
claude
authored and
hyperpolymath
committed
refactor: replace standards-focused docs with actual project vision
This commit recovers the actual Valence Shell project vision after it was overwritten by AI with RSR compliance documentation. What changed: - README.adoc: Now explains what Valence Shell IS (thermodynamic shell, Saga pattern, reversible transactions) instead of listing proof counts - CLAUDE.md: Focused on sacred file protection and project identity - STATE.adoc: NEW - cross-conversation context tracking - HANDOVER.md: NEW - complete context for AI assistants - META.scm: Machine-readable project metadata - ECOSYSTEM.scm: Layer structure and ecosystem position - justfile: Elixir-focused task automation - hooks/pre-commit: Protect sacred files from AI modification The core insight: Valence Shell treats commands as Sagas with compensation. Every operation has an inverse. F⁻¹(F(s)) = s. Phase 1 (current): Hypervisor supervising /bin/sh Phase 2: LD_PRELOAD syscall interception Phase 3: Shell → Elixir AST transpilation
1 parent 3a51fb9 commit 3d473c6

File tree

8 files changed

+1107
-1103
lines changed

8 files changed

+1107
-1103
lines changed

‎CLAUDE.md‎

Lines changed: 79 additions & 411 deletions
Large diffs are not rendered by default.

‎ECOSYSTEM.scm‎

Lines changed: 112 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,112 @@
1-
;; SPDX-License-Identifier: AGPL-3.0-or-later
2-
;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
3-
;; ECOSYSTEM.scm — valence-shell
4-
5-
(ecosystem
6-
(version "1.0.0")
7-
(name "valence-shell")
8-
(type "project")
9-
(purpose "image:https://img.shields.io/badge/RSR-PLATINUM-blueviolet[RSR Compliance]")
10-
11-
(position-in-ecosystem
12-
"Part of hyperpolymath ecosystem. Follows RSR guidelines.")
13-
14-
(related-projects
15-
(project (name "rhodium-standard-repositories")
16-
(url "https://github.com/hyperpolymath/rhodium-standard-repositories")
17-
(relationship "standard")))
18-
19-
(what-this-is "image:https://img.shields.io/badge/RSR-PLATINUM-blueviolet[RSR Compliance]")
20-
(what-this-is-not "- NOT exempt from RSR compliance"))
1+
;; ECOSYSTEM.scm — Valence Shell Entry
2+
;; For inclusion in /overview repository
3+
;;
4+
;; This file documents valence-shell's place in the broader ecosystem.
5+
;; Copy/merge this into the main ECOSYSTEM.scm in /overview
6+
7+
;;; ===================================================================
8+
;;; VALENCE SHELL — Layer 2 Application
9+
;;; ===================================================================
10+
11+
(
12+
(name . "valence-shell")
13+
(display-name . "Valence Shell")
14+
(layer . 2) ; Application layer
15+
(category . "shells-and-runtimes")
16+
17+
(repository
18+
(primary . "gitlab.com/hyperpolymath/valence-shell")
19+
(location . "_maaf/5 shells and target runtimes/valence-shell/"))
20+
21+
(status . active)
22+
(priority . 5) ; Top 5 project
23+
(rsr-tier . rhodium)
24+
25+
(purpose . "Reversible shell with transactional semantics — every command has an inverse")
26+
27+
(languages . ("elixir" "coq"))
28+
(banned . ("python" "typescript"))
29+
30+
;; Relationships
31+
(depends-on
32+
((project . svalinn)
33+
(relationship . "container-base")
34+
(layer . 0))
35+
36+
((project . cerro-torre)
37+
(relationship . "orchestration")
38+
(layer . 0)))
39+
40+
(validated-by
41+
((project . echidna)
42+
(relationship . "proof-verification")
43+
(layer . 3)))
44+
45+
(part-of
46+
((framework . "MAA")
47+
(primitives . ("RMR" "RMO"))))
48+
49+
;; MCP Integration (future)
50+
(mcp-parent . "poly-shell-mcp") ; When created
51+
52+
;; Documentation
53+
(sacred-files . ("README.adoc" "STATE.adoc" "META.scm"))
54+
55+
;; Recovery note
56+
(notes . "README destroyed 2025-12-18, reconstructed from conversation fragments")
57+
)
58+
59+
;;; ===================================================================
60+
;;; RELATED ENTRIES (for context)
61+
;;; ===================================================================
62+
63+
;; These should already exist in ECOSYSTEM.scm, shown here for reference:
64+
65+
#|
66+
;; Layer 0 — Infrastructure (valence-shell depends on these)
67+
(
68+
(name . "svalinn")
69+
(layer . 0)
70+
(category . "infrastructure")
71+
(purpose . "Container security standards and base images")
72+
(repository . "github.com/hyperpolymath/svalinn")
73+
)
74+
75+
(
76+
(name . "cerro-torre")
77+
(layer . 0)
78+
(category . "infrastructure")
79+
(purpose . "Container orchestration patterns")
80+
(repository . "github.com/hyperpolymath/cerro-torre")
81+
)
82+
83+
;; Layer 3 — Solving (validates valence-shell)
84+
(
85+
(name . "echidna")
86+
(layer . 3)
87+
(category . "solving")
88+
(purpose . "Multi-solver proof verification (12+ solvers, neurosymbolic)")
89+
(repository . "github.com/hyperpolymath/echidna")
90+
)
91+
|#
92+
93+
;;; ===================================================================
94+
;;; LAYER STRUCTURE REFERENCE
95+
;;; ===================================================================
96+
97+
#|
98+
Layer 0 — Infrastructure (underpins everything)
99+
└── svalinn, cerro-torre, conative-gating
100+
101+
Layer 1 — MCPs (tool coordination)
102+
└── poly-ssg-mcp, poly-db-mcp, poly-container-mcp, poly-shell-mcp (future)
103+
104+
Layer 2 — Applications (the actual tools)
105+
└── valence-shell, defiant, echomesh, etc.
106+
107+
Layer 3 — Solving (cross-cutting verification)
108+
└── echidna, echidnabot
109+
110+
Overview — The map
111+
└── /overview repository with ECOSYSTEM.scm
112+
|#

‎HANDOVER.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Valence Shell — Handover Document
2+
3+
**Date:** 2025-12-18
4+
**Purpose:** Complete context for AI coding assistants working on this project
5+
**Status:** Project vision recovered after catastrophic loss
6+
7+
---
8+
9+
## CRITICAL: READ CLAUDE.md FIRST
10+
11+
This project experienced **catastrophic data loss** when a previous AI session "helpfully" overwrote the README with framework boilerplate.
12+
13+
**Before doing ANYTHING:**
14+
1. Read `CLAUDE.md` completely
15+
2. Understand which files are SACRED
16+
3. Never modify sacred files without explicit human approval + diff review
17+
18+
---
19+
20+
## Project Summary
21+
22+
**Valence Shell** is a reversible shell where every command is a transaction with an inverse function.
23+
24+
### The Core Insight
25+
26+
Traditional shells destroy information. `rm file` cannot be undone. `mv a b` leaves no trace. Pipelines fail halfway and leave debris.
27+
28+
Valence Shell treats commands as **Sagas** (distributed transaction pattern):
29+
- Every operation has a compensation (inverse)
30+
- External mutations get compensating transactions
31+
- Crashes are recoverable via idempotency journal
32+
- Full undo/redo via Zipper data structure
33+
34+
### The Goal
35+
36+
```
37+
F⁻¹(F(s)) = s — Full reversibility without losing POSIX compliance
38+
```
39+
40+
---
41+
42+
## Architecture
43+
44+
### The Three Phases
45+
46+
| Phase | Name | Description | Status |
47+
|-------|------|-------------|--------|
48+
| 1 | Hypervisor | Supervise `/bin/sh`, intercept known commands | **Current** |
49+
| 2 | Hybrid Shim | `LD_PRELOAD` syscall interception | Future |
50+
| 3 | AST Transpiler | Parse shell → Elixir AST | Dream |
51+
52+
### Core Components
53+
54+
```
55+
lib/valence/
56+
├── command.ex # Valence.Command behaviour (4 callbacks)
57+
├── commands/ # Native reversible implementations
58+
│ ├── file_ops.ex # cp, mv, rm, touch, etc.
59+
│ ├── directory.ex # mkdir, rmdir, cd
60+
│ └── ...
61+
├── history/
62+
│ ├── zipper.ex # In-memory undo/redo (O(1))
63+
│ └── journal.ex # Idempotency + crash recovery
64+
├── saga.ex # Compensating transaction orchestration
65+
└── supervisor.ex # OTP supervision tree
66+
```
67+
68+
### The Command Contract
69+
70+
Every reversible operation implements:
71+
72+
```elixir
73+
@callback describe(args) :: :safe | :warn | :danger
74+
# How risky is this operation?
75+
76+
@callback execute(args, idempotency_key) :: {:ok, result, compensation} | {:error, reason}
77+
# Do the thing, return its inverse
78+
79+
@callback compensate(args, idempotency_key) :: :ok | {:error, reason}
80+
# Undo the thing
81+
82+
@callback verify(args) :: :ok | {:drift, expected, actual}
83+
# Did reality match expectations?
84+
```
85+
86+
---
87+
88+
## Technology Decisions
89+
90+
### Stack
91+
92+
| Component | Choice | Rationale |
93+
|-----------|--------|-----------|
94+
| Runtime | Elixir/OTP | Supervision trees, pattern matching, no Python |
95+
| Transactions | Ecto | Changesets without database coupling |
96+
| History | Zipper | O(1) undo/redo, functional |
97+
| Proofs | Coq | Machine-checked, ECHIDNA integration |
98+
| Containers | Svalinn/Cerro Torre | Project standards |
99+
| HTTP | Bandit | Optional API/GUI interface |
100+
101+
### Banned (RSR Policy)
102+
103+
- Python (if you see .py files, they're contamination)
104+
- TypeScript
105+
- Docker (use Podman)
106+
- npm (use Deno if JS needed)
107+
- GitHub Actions (use GitLab CI)
108+
109+
---
110+
111+
## Integration Points
112+
113+
### MAA Framework
114+
115+
Valence Shell implements:
116+
- **RMR (Reversible Mutation Record)** — Every command generates a record with its inverse
117+
- **RMO (Reversible Mutation Obliteration)** — Secure deletion with proof (when needed)
118+
119+
### ECHIDNA
120+
121+
The formal proof (`proofs/coq/rmr.v`) proving `F⁻¹(F(s)) = s` is verified by ECHIDNA's multi-solver integration (12+ solvers, neurosymbolic).
122+
123+
### Container Standards
124+
125+
- Base images: Svalinn (`github.com/hyperpolymath/svalinn`)
126+
- Orchestration: Cerro Torre (`github.com/hyperpolymath/cerro-torre`)
127+
128+
---
129+
130+
## Current State
131+
132+
**As of 2025-12-18:**
133+
134+
- README.adoc: Recovered (was destroyed)
135+
- Project structure: Not scaffolded yet
136+
- Elixir code: Not written
137+
- Coq proofs: Not written
138+
- Tests: Not written
139+
140+
**Next Steps:**
141+
142+
1. Scaffold Elixir project with `mix new valence_shell --sup`
143+
2. Create `Valence.Command` behaviour
144+
3. Implement `Valence.History.Zipper`
145+
4. Implement first native command (`file_ops.ex`)
146+
5. Add property tests with StreamData
147+
148+
---
149+
150+
## Files in This Recovery Package
151+
152+
| File | Purpose |
153+
|------|---------|
154+
| `README.adoc` | Vision document — **SACRED** |
155+
| `CLAUDE.md` | AI protection rules |
156+
| `STATE.adoc` | Cross-conversation context — append only |
157+
| `META.scm` | Machine-readable metadata |
158+
| `ECOSYSTEM.scm` | Entry for /overview |
159+
| `HANDOVER.md` | This file |
160+
161+
---
162+
163+
## Commands
164+
165+
Once scaffolded:
166+
167+
```bash
168+
just deps # mix deps.get
169+
just verify # mix test + property tests
170+
just prove # Run Coq proofs
171+
just run # Start the shell
172+
```
173+
174+
---
175+
176+
## Questions to Resolve
177+
178+
1. **Phase 2 syscall interception:** `LD_PRELOAD` vs `ptrace` vs eBPF?
179+
2. **Shell parser for Phase 3:** Tree-sitter? Custom PEG?
180+
3. **Compensation storage:** SQLite? Mnesia? Plain files?
181+
4. **GUI:** LiveView dashboard for history visualisation?
182+
183+
---
184+
185+
## Recovery Context
186+
187+
This README was destroyed on 2025-12-18 when an AI assistant overwrote it with generic RSR framework content. The project vision was reconstructed from:
188+
189+
- Conversation fragments across multiple Claude sessions
190+
- User's notes about thermodynamic shell concept
191+
- Saga pattern documentation
192+
- MAA Framework integration details
193+
194+
Some original wording and specific implementation decisions were lost forever. This reconstruction represents the best recovery possible from available fragments.
195+
196+
**Lesson:** AI assistants will "helpfully" destroy your work. Use CLAUDE.md, git hooks, file permissions, and branch protection to prevent this.
197+
198+
---
199+
200+
## Contact
201+
202+
Jonathan D.A. Jewell
203+
jonathan.jewell@open.ac.uk
204+
The Open University

0 commit comments

Comments
 (0)