feat: scaffold Elixir project with core reversibility infrastructure

Phase 1 foundation - the Hypervisor pattern:

Core modules:
- Valence.Command - 4-callback behaviour for reversible operations
  - describe/1 → :safe | :warn | :danger
  - execute/2 → {:ok, result, compensation}
  - compensate/2 → undo the operation
  - verify/1 → detect drift (Two Generals)

- Valence.History.Zipper - O(1) undo/redo without state copying
  - push/back/forward in constant time
  - Functional, immutable structure

- Valence.Journal - Idempotency for crash recovery
  - Track pending/completed/compensated states
  - Same key = cached result (no re-execution)

- Valence.Saga - Compensating transaction coordinator
  - Multi-step operations as atomic units
  - Automatic rollback on failure

Sample commands:
- Directory.Mkdir / Directory.Rmdir
- FileOps.Touch / FileOps.Rm / FileOps.Write

Proofs:
- proofs/coq/rmr.v - Reversibility axiom F⁻¹(F(s)) = s

Tests:
- Zipper unit tests
- Property-based tests with StreamData

Author: claude

.formatter.exs

@@ -0,0 +1,3 @@
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

lib/valence.ex

@@ -0,0 +1,48 @@
+defmodule Valence do
+  @moduledoc """
+  Valence Shell - The Thermodynamic Shell
+
+  Every command is a reversible transaction. Every mutation is accountable.
+
+  ## Core Principle
+
+      F⁻¹(F(s)) = s
+
+  Full reversibility without sacrificing POSIX compliance.
+
+  ## Architecture
+
+  - `Valence.Command` - Behaviour for reversible operations
+  - `Valence.History.Zipper` - O(1) undo/redo structure
+  - `Valence.Saga` - Compensating transaction orchestration
+  - `Valence.Journal` - Idempotency and crash recovery
+  """
+
+  @doc """
+  Execute a command with full transaction semantics.
+
+  Returns `{:ok, result}` on success, `{:error, reason}` on failure.
+  On failure, any partial mutations are automatically compensated.
+  """
+  def execute(command, args) do
+    Valence.Saga.execute(command, args)
+  end
+
+  @doc """
+  Undo the last operation.
+
+  Returns `{:ok, previous_state}` or `{:error, :nothing_to_undo}`.
+  """
+  def undo do
+    Valence.History.undo()
+  end
+
+  @doc """
+  Redo the last undone operation.
+
+  Returns `{:ok, restored_state}` or `{:error, :nothing_to_redo}`.
+  """
+  def redo do
+    Valence.History.redo()
+  end
+end

lib/valence/application.ex

@@ -0,0 +1,28 @@
+defmodule Valence.Application do
+  @moduledoc """
+  OTP Application for Valence Shell.
+
+  Supervises:
+  - History (Zipper state for undo/redo)
+  - Journal (Idempotency log for crash recovery)
+  - Saga (Compensating transaction coordinator)
+  """
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      # In-memory undo/redo history
+      Valence.History,
+
+      # Idempotency journal for crash recovery
+      Valence.Journal,
+
+      # Saga coordinator for multi-step transactions
+      Valence.Saga
+    ]
+
+    opts = [strategy: :one_for_one, name: Valence.Supervisor]
+    Supervisor.start_link(children, opts)
+  end
+end

lib/valence/command.ex

@@ -0,0 +1,100 @@
+defmodule Valence.Command do
+  @moduledoc """
+  Behaviour for reversible shell commands.
+
+  Every command in Valence Shell must implement these four callbacks,
+  ensuring full reversibility and accountability.
+
+  ## The Contract
+
+  ```elixir
+  @callback describe(args) :: :safe | :warn | :danger
+  @callback execute(args, idempotency_key) :: {:ok, result, compensation} | {:error, reason}
+  @callback compensate(args, idempotency_key) :: :ok | {:error, reason}
+  @callback verify(args) :: :ok | {:drift, expected, actual}
+  ```
+
+  ## Example Implementation
+
+  ```elixir
+  defmodule Valence.Commands.Mkdir do
+    @behaviour Valence.Command
+
+    @impl true
+    def describe(%{path: _path}), do: :safe
+
+    @impl true
+    def execute(%{path: path}, idempotency_key) do
+      case File.mkdir(path) do
+        :ok ->
+          compensation = %{module: __MODULE__, action: :rmdir, args: %{path: path}}
+          {:ok, :created, compensation}
+        {:error, reason} ->
+          {:error, reason}
+      end
+    end
+
+    @impl true
+    def compensate(%{path: path}, _idempotency_key) do
+      File.rmdir(path)
+    end
+
+    @impl true
+    def verify(%{path: path}) do
+      if File.dir?(path), do: :ok, else: {:drift, :exists, :missing}
+    end
+  end
+  ```
+  """
+
+  @type args :: map()
+  @type idempotency_key :: binary()
+  @type compensation :: %{module: module(), action: atom(), args: map()}
+  @type risk_level :: :safe | :warn | :danger
+
+  @doc """
+  Assess the thermodynamic cost of this operation.
+
+  - `:safe` - Reversible with no external effects
+  - `:warn` - Reversible but may have observable side effects
+  - `:danger` - May be irreversible or affect external systems
+  """
+  @callback describe(args()) :: risk_level()
+
+  @doc """
+  Execute the command and return its compensation.
+
+  The idempotency key ensures crash recovery - if this key has already
+  been executed, return the cached result instead of re-executing.
+
+  Returns:
+  - `{:ok, result, compensation}` - Success with undo information
+  - `{:error, reason}` - Failure (no compensation needed)
+  """
+  @callback execute(args(), idempotency_key()) ::
+              {:ok, term(), compensation()} | {:error, term()}
+
+  @doc """
+  Undo the effects of a previous execution.
+
+  This is the inverse function: if `execute` did F(s), then
+  `compensate` does F⁻¹(F(s)) = s.
+  """
+  @callback compensate(args(), idempotency_key()) :: :ok | {:error, term()}
+
+  @doc """
+  Verify the expected state matches reality.
+
+  Used for Two Generals problem detection - did the operation actually
+  complete, or is there drift between expected and actual state?
+  """
+  @callback verify(args()) :: :ok | {:drift, expected :: term(), actual :: term()}
+
+  @doc """
+  Check if a module implements the Command behaviour.
+  """
+  def command?(module) when is_atom(module) do
+    behaviours = module.module_info(:attributes)[:behaviour] || []
+    __MODULE__ in behaviours
+  end
+end

lib/valence/commands/directory.ex

@@ -0,0 +1,88 @@
+defmodule Valence.Commands.Directory do
+  @moduledoc """
+  Reversible directory operations.
+
+  Implements:
+  - `mkdir` / `rmdir` (proven reversible: rmdir(mkdir(p)) = identity)
+  """
+
+  defmodule Mkdir do
+    @moduledoc "Create a directory. Compensation: remove it."
+    @behaviour Valence.Command
+
+    @impl true
+    def describe(%{path: _path}), do: :safe
+
+    @impl true
+    def execute(%{path: path}, _idempotency_key) do
+      case File.mkdir_p(path) do
+        :ok ->
+          compensation = %{
+            module: Rmdir,
+            action: :compensate,
+            args: %{path: path}
+          }
+          {:ok, :created, compensation}
+
+        {:error, reason} ->
+          {:error, reason}
+      end
+    end
+
+    @impl true
+    def compensate(%{path: path}, _idempotency_key) do
+      case File.rmdir(path) do
+        :ok -> :ok
+        {:error, reason} -> {:error, reason}
+      end
+    end
+
+    @impl true
+    def verify(%{path: path}) do
+      if File.dir?(path) do
+        :ok
+      else
+        {:drift, :directory_exists, :missing}
+      end
+    end
+  end
+
+  defmodule Rmdir do
+    @moduledoc "Remove an empty directory. Compensation: recreate it."
+    @behaviour Valence.Command
+
+    @impl true
+    def describe(%{path: _path}), do: :warn  # Could fail if not empty
+
+    @impl true
+    def execute(%{path: path}, _idempotency_key) do
+      # Capture state for compensation
+      case File.rmdir(path) do
+        :ok ->
+          compensation = %{
+            module: Mkdir,
+            action: :compensate,
+            args: %{path: path}
+          }
+          {:ok, :removed, compensation}
+
+        {:error, reason} ->
+          {:error, reason}
+      end
+    end
+
+    @impl true
+    def compensate(%{path: path}, _idempotency_key) do
+      File.mkdir_p(path)
+    end
+
+    @impl true
+    def verify(%{path: path}) do
+      if File.dir?(path) do
+        {:drift, :removed, :still_exists}
+      else
+        :ok
+      end
+    end
+  end
+end