Valence Shell

Table of Contents

• The Thermodynamic Shell
• Why This Matters
  • The Problem with Shells
  • The Valence Solution
• Architecture
  • Core Principles
  • The Command Contract
  • Safety Net Layers
• Roadmap
  • Phase 1: The Hypervisor (Current)
  • Phase 2: The Hybrid Shim
  • Phase 3: The AST Transpiler (The Dream)
• Technology Stack
• Integration with MAA Framework
• Building
• Project Structure
• Licence
• Related Projects

The Thermodynamic Shell

Valence Shell is a reversible shell that treats commands not as fire-and-forget instructions, but as transactions with inverses.

Where traditional shells mutate state irreversibly, Valence expends computational resources to maintain a complete reversible history. Every operation can be undone. Every mutation is accountable.

Full reversibility: F⁻¹(F(s)) = s — without sacrificing POSIX compliance.

Why This Matters

The Problem with Shells

Traditional shells are thermodynamically wasteful. They:

• Destroy information (you cannot un-rm)

• Provide no audit trail (what changed and when?)

• Fail partially (half-completed pipelines leave debris)

• Offer no compensation (external systems stay mutated)

The Valence Solution

Valence Shell implements the Saga pattern at the shell level:

Domain	Traditional Shell	Valence Shell
Files	Destructive mutation	Shadow copies + Git integration
Network/DB	Fire and forget	Compensating transactions
Pipelines	Partial failure	All-or-nothing with rollback
History	Text log	Zipper structure with semantic undo

Architecture

Core Principles

1. Ecto at Core — Every shell operation is a database transaction. This isn’t about storage; it’s about transactional semantics, rollback, and query.

2. Zipper Memory — In-memory history uses a Zipper (cursor in a list), enabling O(1) undo/redo without copying state.

3. Idempotency Keys — Every command gets a unique key (local CURP equivalent). Crash recovery checks the journal: did this command complete?

4. Compensating Actions — External systems (APIs, databases, network) cannot be "rolled back", so Valence generates and stores compensating transactions.

The Command Contract

Every atomic operation implements the Valence.Command behaviour:

@callback describe(args :: map()) :: :safe | :warn | :danger
  # Thermodynamic cost assessment

@callback execute(args :: map(), idempotency_key :: binary()) ::
  {:ok, result, compensation} | {:error, reason}
  # Perform the action, return its inverse

@callback compensate(args :: map(), idempotency_key :: binary()) ::
  :ok | {:error, reason}
  # The inverse function (undo)

@callback verify(args :: map()) ::
  :ok | {:drift, expected, actual}
  # Two Generals check: does state match expectations?

Safety Net Layers

┌─────────────────────────────────────────────────────────────┐
│                    Valence Shell                            │
├─────────────────────────────────────────────────────────────┤
│  In-Memory: Zipper structure for instant undo/redo          │
├─────────────────────────────────────────────────────────────┤
│  Files: Git (project) or Shadow Copies (system)             │
├─────────────────────────────────────────────────────────────┤
│  External: Compensating Transactions (Saga Pattern)         │
├─────────────────────────────────────────────────────────────┤
│  Crash Recovery: Idempotency journal with completion flags  │
└─────────────────────────────────────────────────────────────┘

Roadmap

Phase 1: The Hypervisor (Current)

Valence supervises a standard /bin/sh process:

• "Native Reversible" commands (file ops, etc.) execute in Elixir with full transaction semantics

• Unrecognised commands pass through to the underlying shell

• All output captured for history

This provides immediate value: reversible file operations today, POSIX compatibility preserved.

Phase 2: The Hybrid Shim

Intercept syscalls from standard binaries:

• LD_PRELOAD or ptrace to catch filesystem mutations

• Copy-on-write enforcement at syscall level

• Transparent to the binary being run

This extends reversibility to any command, not just native ones.

Phase 3: The AST Transpiler (The Dream)

Parse shell syntax into Elixir AST:

• Static analysis before execution

• Identify side effects at parse time

• Generate compensation automatically

• Full semantic understanding of pipelines

Technology Stack

Component	Technology
Core Runtime	Elixir (OTP Application)
Transaction Semantics	Ecto (schemas, changesets, transactions)
Web Interface	Bandit (HTTP server for optional GUI/API)
Idempotency	UUID generation per command
Property Testing	StreamData (statistically significant verification)
Formal Proofs	Coq (reversibility axiom in proofs/coq/rmr.v)
Containers	Svalinn base images, Cerro Torre orchestration

Integration with MAA Framework

Valence Shell is an instantiation of the MAA (Mutually Assured Accountability) Framework:

• RMR (Reversible Mutation Records) — Every command generates a record containing its inverse function

• RMO (Reversible Mutation Obliteration) — Secure deletion with cryptographic proof (when needed)

The formal properties are verified by ECHIDNA multi-solver integration.

Building

# Dependencies
mix deps.get

# Verify (tests + property checks)
just verify

# Run proofs (requires Coq)
just prove

# Start shell
just run

Project Structure

valence-shell/
├── lib/
│   ├── valence/
│   │   ├── command.ex          # Behaviour definition
│   │   ├── commands/           # Native reversible commands
│   │   │   ├── file_ops.ex
│   │   │   ├── directory.ex
│   │   │   └── ...
│   │   ├── history/
│   │   │   ├── zipper.ex       # In-memory undo/redo
│   │   │   └── journal.ex      # Persistent idempotency log
│   │   ├── saga.ex             # Compensation orchestration
│   │   └── supervisor.ex       # OTP supervision tree
│   └── valence.ex
├── proofs/
│   └── coq/
│       └── rmr.v               # Reversibility axiom
├── test/
├── mix.exs
├── justfile
└── README.adoc                 # You are here

Licence

AGPL-3.0 with Palimpsest overlay.

Related Projects

• Svalinn — Container security standards

• Cerro Torre — Container orchestration

• ECHIDNA — Multi-solver proof verification

• Conative Gating — AI enforcement layer

• JanusKey — MAA Framework reference implementation