Open v2 session: Shape A — Rust interpreter + graph-native parallel runtime

Author: Douglas Jones

sessions/2026-05-12.md

@@ -0,0 +1,138 @@
+---
+session: 2026-05-12
+status: open
+v2_shape: A
+v2_decision: "Shape A — Rust interpreter + graph-native parallel runtime"
+python_tests: 216
+rust_tests: 28
+capability_manifest_hash: sha256:23fdde779caebc2c471ade0e1c407422d044e2e0f1adc7e59a189325deccd27d
+---
+
+# Session state — 2026-05-12
+
+## How to resume
+
+1. `python3 -m codifide test` — confirm 216/216 passing, 0 skipped.
+2. `cargo test --release -p codifide-canonical` — confirm 28/28 passing.
+3. Read this file. That's all you need.
+
+## Where we are
+
+v1.0.0 shipped on 2026-05-11. Tagged, pushed to
+`https://github.com/codifide/CodifideProgrammingLanguage`.
+
+The v2 shape decision is **Shape A: the runtime agents can actually use.**
+
+## What Shape A means
+
+**Thesis.** Codifide's correctness claim is verified. Now its
+performance and concurrency claims need to be.
+
+**Scope (from `dispatches/2026-05-11-v2-thinking.readout.md`):**
+
+1. **Rust interpreter port.** The whole evaluator, not just the
+   canonical form. Python reference stays as the spec; Rust becomes
+   the production runtime. Expected 10-100× speedup on realistic
+   programs.
+
+2. **Graph-native parallel evaluator.** Today's tree-walker evaluates
+   sequentially even when the dataflow graph has independent branches.
+   A real implementation parallelizes at the node level. This is in
+   the original seven design principles ("parallelism is default;
+   sequencing is declared") and v1 does not deliver on it.
+
+3. **Effect-scoped concurrency model.** If two branches share an
+   `io.stdout` effect, they must serialize; if their effect sets are
+   disjoint, they can run in parallel. The effect algebra already
+   tells us what is safe; the runtime just has to honor it.
+
+4. **Benchmarks as first-class citizens.** Every example gets a
+   performance fixture. Regressions are regressions.
+
+**Estimated scope:** 2-3 sessions.
+
+**Biggest risk:** porting a moving target. Mitigation: the spec is
+now written, audited, and stable. The target is less moving than
+when we first deferred this work.
+
+## What the new session should do first
+
+1. **File the v2-A session-open dispatch** (Quill + Glyph pair).
+   Records the decision, the scope, and the first proposal.
+
+2. **File the Rust interpreter proposal dispatch** with a Sable
+   audit. Per `GOVERNANCE.md`, a new capability of this scope needs
+   a proposal + audit + Douglas's approval before implementation
+   starts. The proposal should cover:
+   - Which semantics the Rust interpreter must match (Python is the
+     spec; Rust must pass the same test suite).
+   - How the two runtimes coexist during the port (Python stays
+     default; Rust is opt-in via a flag until it passes all tests).
+   - What the conformance surface looks like (extend
+     `tests/test_conformance.py` to cover runtime behavior, not just
+     canonical bytes).
+   - How the graph-native evaluator relates to the tree-walker
+     (same semantics, different execution order for pure branches).
+
+3. **Start the Rust interpreter implementation** once the proposal
+   is approved.
+
+## Key files to read before starting
+
+| What | Where |
+|---|---|
+| v1 state | `sessions/2026-05-11.md` |
+| v2 shape options | `dispatches/2026-05-11-v2-thinking.readout.md` |
+| v1 release | `dispatches/2026-05-11-v1-release.readout.md` |
+| Interpreter (Python reference) | `codifide/runtime/interpreter.py` |
+| Canonical form spec | `docs/CANONICAL.md` |
+| Dispatch semantics | `docs/CANONICAL.md §Dispatch` |
+| Effect algebra | `docs/CANONICAL.md §Effect algebra` |
+| Rust crate (canonical form only) | `crates/codifide-canonical/src/` |
+| Governance | `GOVERNANCE.md` |
+
+## What the Rust interpreter needs to implement
+
+The Python interpreter in `codifide/runtime/interpreter.py` is the
+reference. The Rust port must match it on:
+
+- Candidate dispatch (including cost-based selection).
+- Effect enforcement (primitive-call half + transitive half).
+- Contract evaluation (pre/post/guard with empty effect budget).
+- Belief dispatch (`believe` blocks).
+- Inline conditional (`if ... then ... else`, short-circuit).
+- First-class refusal (`bottom`, `RefusalError`).
+- Recursion limit (default 64, typed `RecursionLimitError`).
+- All eight typed error classes.
+- Import resolution through the symbol store.
+
+The graph-native parallel evaluator is a second step after the
+tree-walker port passes all tests. Don't parallelize until the
+sequential semantics are confirmed correct.
+
+## Persona usage reminder
+
+- **Sable** runs at gate transitions. The Rust interpreter proposal
+  needs a Sable audit before implementation starts.
+- **Quill** writes `.readout.md`. Match the register: direct, no
+  superlatives, end with "What I'm not yet sure of."
+- **Glyph** writes paired `.yaml`. Same `subject` as Quill. Every
+  claim needs evidence; `unknowns:` is never empty.
+- **Decisions** get a `*-decisions.{readout.md,yaml}` pair with
+  explicit yes/no and one-paragraph rationale per item.
+
+## v2 version target
+
+- Python package: `2.0.0` (bump when the Rust interpreter passes
+  all tests and is the default runtime).
+- Rust crate: `2.0.0` (same milestone).
+- Capability manifest: will move when the runtime surface changes
+  (e.g., if the parallel evaluator adds new effect semantics).
+
+## What v2-A does NOT include
+
+- Shape B (protocol/network) — deferred to v3.
+- Shape C (expressiveness: time-indexed types, type inference,
+  structural diff) — deferred to v3 or v4.
+- External-model re-run — still a pre-v2 recommendation, but not
+  blocking. Can happen in parallel with the Rust port.