Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 55 additions & 37 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,31 +22,47 @@ Opus audit session that fixed all broken tests, real bugs, and documentation.

### What Actually Works (v0.9.0)

The Rust CLI is a functional interactive shell with these features:

- Built-in filesystem operations (mkdir, rmdir, touch, rm) with undo/redo
- External command execution via PATH lookup
- Reversible file operations (`cp`, `mv`, `ln -s`) with formal proofs
- Unix pipelines (`cmd1 | cmd2 | cmd3`)
- I/O redirections (`>`, `>>`, `<`, `2>`, `2>>`, `&>`, `2>&1`)
- Process substitution (`<(cmd)` and `>(cmd)`)
- Arithmetic expansion (`$((expr))`)
- Here documents (`<<DELIM`) and here strings (`<<<word`)
- Glob expansion (`*.txt`, `file?.rs`, `[a-z]*`, `{1,2,3}`)
- Quote processing (single, double, backslash)
- Control structures (`if/then/elif/else/fi`, `while/do/done`, `for/in/do/done`, `case/esac`)
- `test`/`[` and `[[ ]]` conditionals
- Logical operators (`&&` `||`) with short-circuit evaluation
- Shell builtins (`echo`, `read`, `source`, `eval`, `set`, `unset`, `true`, `false`)
- Shell variables (`$VAR`, `${VAR}`, `export`) with reversible assignment (undo/redo)
- Job control (`bg`, `fg`, `jobs`, `kill`, `&` operator)
**Measured, not claimed (2026-11-17, gate G0).** `impl/rust-cli/tests/conformance_battery.rs`
starts the built shell on 128 everyday command lines and compares the result with bash:
**69 match**. The cases that fail are listed in
`impl/rust-cli/tests/conformance/known_failing.txt`. That list is a ratchet: it may only
shrink, and a case may not be added to it to make a build pass.

Works through the built shell (passing battery cases, or checked by hand interactively):

- Built-in file operations with undo/redo (`mkdir`, `rmdir`, `touch`, `rm`, `cp`, `mv`,
`ln -s`, `chmod`, `chown`) in their plain forms only: one operand each, two for `cp`,
`mv` and `ln -s`, and a mode or an owner followed by one file for `chmod` and `chown`. None
takes an option (the `-s` of `ln -s` apart). An option or an extra operand is refused, and
nothing is done
- External command execution via PATH lookup; pipelines of external programs
- `>`, `>>`, `<` and here strings (`<<<word`); `&&` and `||`
- `test`, `[ ... ]`, and `[[ ... ]]` on its own; `if/elif/else`, `while`, a single `for`, `case`
- Functions, `local`, `return`; `$VAR`, `${VAR}`, `${VAR:-default}`, `${#VAR}`, `${VAR:o:n}`
- `$((expr))`, and `$(cmd)` of another program, as the whole value of an assignment
- `echo`, `printf`, `eval`, `set --`, `set -e`, `alias`, `trap ... EXIT`, `exit N`
- A command that fails fails only itself, with a status: the next command of a script,
a function or a loop runs, and `||` runs its right side
Comment thread
hyperpolymath marked this conversation as resolved.
Resolved
- Reversible variable assignment (undo/redo)
- Transaction grouping (`begin`/`commit`/`rollback`)
- Interactive REPL with history and multi-line input for control structures
- Command correction (zsh-style "Did you mean?")
- `explain` command (proof-annotated dry runs)
- `checkpoint`/`restore` (named snapshots with proof certificates)
- `diff` (state comparison between checkpoints or current state)
- `replay` (animated history with proof narration)
- `explain`, `checkpoint`/`restore`, `diff`, `replay`, `history --proofs`
- Interactive REPL: line editing, history, multi-line control structures, `help`,
`&` at the end of a line and `jobs`

In the source and unit-tested, but NOT working through the built shell (battery cases fail):

- Glob, brace and tilde expansion: applied only when the command also has a redirection
- `$((expr))` and `$(cmd)` inside an argument (`echo $((1+2))` prints the text); backquotes
- A quoted `*`, `?`, `[`, `{` or `~` reaches other programs with a backslash added
- `${VAR#pat}`, `${VAR%pat}`, `${VAR^^}` (give an empty string); `$$`
- Nested `for` loops (silently wrong), `break`, `continue`, `! cmd`
- Subshells, brace groups in pipelines, arrays, `(( ))`, the C-style `for`
- `export` and `VAR=value cmd` do not reach the program being run
- Here documents passed with `-c`; redirections on built-in commands outside the session root
(`ls nosuch 2>/dev/null`)
- Ctrl-Z does not suspend a running program

Not exercised by the battery: process substitution, command correction, the pager.

### Proof policy (normative, estate-wide)

Expand Down Expand Up @@ -271,29 +287,31 @@ vsh::parser::expand_variables(&input, &state);

### Immediate Priorities

1. **Word splitting in external command arguments** (requires quote-context threading)
2. **Alias expansion in pipe segments** (currently only first command in a pipeline)
3. **Echidna integration** for automated property-based verification
4. **`~user` tilde expansion** (requires getpwnam/NSS lookup)

### This Week
**The shell-language items that used to be listed here are parked** (owner ruling OD-42,
2026-11-17; recorded in `docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc` on valence-shell#230,
with the measurements in `docs/plans/VSH-PRODUCT-REVIEW-2026-11-17.adoc`). The engine is
the product: reversible operations, the journal, containment, the record, and the proofs.
The interpreter is one front end and comes last.

1. Implement shell functions (`func() { ... }`)
2. Shell script execution (`.sh` files)
3. Set up Echidna property-based validation pipeline
Forward order:

### This Month
1. **S0, the truthful baseline** (gate G0): what is claimed equals what the battery shows
2. **The engine** (route plan phases B, C3 to C5, D, E): runtime holes, state outside the
tree, a store for old file contents, the spec spine, contracts on the Rust core
3. **The capture experiment** (undo for any command), which decides the first front end

1. Implement shell functions (`func() { ... }`)
2. Shell script execution (`.sh` files)
3. Begin Idris2 extraction path for v2.0
Do not spend effort on POSIX coverage of the interpreter (word splitting, `~user`, alias
expansion in pipelines) unless the owner asks for it.

### What NOT to Do

- Do NOT claim this is production-ready
- Do NOT inflate version numbers
- Do NOT add features before closing proof holes
- Do NOT trust Sonnet's commit messages or claims without verification
- Do NOT add a case to `tests/conformance/known_failing.txt` to get a green build: fix the
shell, or correct a wrong expectation and say why
- Do NOT tick a feature as working unless a test that runs the built shell shows it

## Building and Testing

Expand Down
25 changes: 17 additions & 8 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -50,19 +50,28 @@ Valence Shell is a formally verified shell with proven reversibility guarantees.
* [x] MAA Framework: Mutually Assured Accountability with audit trails

== Shell Features (v0.9.0)
* [x] Unix Pipelines: Multi-stage pipelines (`cmd1 | cmd2 | cmd3`)
* [x] I/O Redirections: All POSIX redirections (`>`, `>>`, `<`, `2>`, `2>>`, `&>`, `2>&1`)
* [x] Process Substitution: `<(cmd)` and `>(cmd)` with FIFO implementation
* [x] Arithmetic Expansion: `$expr` with full operator support
* [x] Here Documents: `<<DELIMITER`, `<←DELIMITER`, `<<<word`
* [x] Job Control: Background jobs, `fg`, `bg`, `kill`, job specifications
* [x] Shell Variables: `$VAR`, `export`, assignment, expansion

[NOTE]
====
*Measured, not claimed.* `impl/rust-cli/tests/conformance_battery.rs` starts the built shell on 128 everyday command lines and compares the result with bash. On 2026-11-18, 69 match. The cases that fail are listed in `impl/rust-cli/tests/conformance/known_failing.txt`, which may only shrink. Below, `[x]` means it works through the built shell, `[~]` means in part, and the limit is stated.
====

* [~] Built-in file commands with undo: `mkdir`, `rmdir`, `touch`, `rm`, `cp`, `mv`, `ln -s`, `chmod`, `chown`, in their plain forms only (one operand each; two for `cp`, `mv` and `ln -s`; a mode or an owner and then one file for `chmod` and `chown`; no options, the `-s` of `ln -s` apart). An option or an extra operand is refused and nothing is done
* [ ] Wildcard, brace and tilde expansion: applied only when the command also has a redirection
* [ ] Quoting: a quoted `*`, `?`, `[`, `{` or `~` reaches other programs with a backslash added
* [x] Unix Pipelines: Multi-stage pipelines of external programs (`cmd1 | cmd2 | cmd3`)
* [~] I/O Redirections: `>`, `>>`, `<` and here strings work. A redirection on a built-in command is resolved inside the session root, so `2>/dev/null` fails there
* [~] Process Substitution: `<(cmd)` and `>(cmd)` are in the source; not exercised by the battery
* [~] Arithmetic Expansion: `$((expr))` works as the whole value of an assignment, not inside an argument
* [~] Here Documents: here strings (`<<<word`) work; a here document passed with `-c` does not
* [~] Job Control: `&` at the end of a line and `jobs` work; Ctrl-Z does not suspend a running program
* [~] Shell Variables: assignment and expansion work; `export` does not reach the programs that are run
* [~] RMO: `obliterate` implements best-effort 3-pass file overwrite + unlink + an unsigned audit residue; CoW filesystems, SSD remapping, snapshots, replicas, crash timing, and legal compliance remain outside that guarantee. Audit-log HMAC chaining is available when a key is supplied, but RMO does not yet provision one. See link:docs/RMO-DURABILITY-BOUNDARY.adoc[the exact boundary].
* [x] Syntax Highlighting: Real-time color-coded REPL
* [x] Command Correction: Intelligent typo suggestions
* [x] Friendly Errors: fish-style helpful error messages
* [x] Smart Pager: Auto-paging for long output
* [x] 3-Tier Help: Quick/verbose/man page documentation
* [x] Help: `help` lists the commands and `help <command>` describes one; there are no manual pages
* [x] 794 Tests Passing: Unit, correspondence, integration, property, security, doctests (0 failures, 14 ignored) — `tested-only` in the proof ledger, not proofs

== Implementation
Expand Down
5 changes: 5 additions & 0 deletions ROADMAP.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,11 @@ integration), #56/#57/#58 (the three admits surfaced by #55).

== v0.10.x — POSIX Coverage

[IMPORTANT]
====
*Parked* by owner ruling OD-42 (2026-11-17; recorded in `docs/plans/VSH-ROUTE-PLAN-2026-11-04.adoc` on valence-shell#230). The engine is the product and the shell interpreter is one front end, which comes last. What the interpreter does today is measured by `impl/rust-cli/tests/conformance_battery.rs` (69 of 128 command lines match bash), not by the list below, parts of which are out of date.
====

Most critical missing POSIX features, ranked by impact (per CLAUDE.md
and `docs/POSIX_COMPLIANCE.md`):

Expand Down
5 changes: 5 additions & 0 deletions impl/rust-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,11 @@ which = "7.0"
proptest = "1.10"
tempfile = "3.26"

# Pseudo-terminal for the tests that run the built shell at its prompt
# (tests/function_frame_tests.rs). Same crate and version as above; the `term`
# feature is turned on for test builds only.
nix = { version = "0.31", default-features = false, features = ["fs", "term"] }

# Benchmarking
criterion = "0.5"

Expand Down
Loading
Loading