build: containerized cross-platform dev environment

Add a Docker toolchain image so the workspace builds and tests identically on
macOS, Windows, and Linux with no local Rust/C/SQLite install.

- Dockerfile: rust:1-bookworm (satisfies edition 2024) + build-essential, cmake,
  pkg-config (for ring/rustls and bundled rusqlite), clippy/rustfmt, and
  cargo-nextest (arch-aware prebuilt for amd64/arm64). A profile.d snippet keeps
  cargo on PATH for login shells too.
- compose.yaml: `dev` service bind-mounts the repo at /work; target/ and cargo
  caches live in named volumes (off the host mount) so builds persist and stay
  fast on macOS/Windows.
- .devcontainer: VS Code / Codespaces reuse the same compose service.
- .dockerignore, docs/DOCKER.md, and README/docs-index pointers.

Verified on Apple Silicon (OrbStack): image builds, workspace compiles
in-container, and `cargo nextest` runs the suite green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: olwang

.devcontainer/devcontainer.json

@@ -0,0 +1,23 @@
+{
+  "name": "RSScript Dev",
+  "dockerComposeFile": ["../compose.yaml"],
+  "service": "dev",
+  "workspaceFolder": "/work",
+  // Reuse the same toolchain image, caches, and system libraries as the
+  // `docker compose` workflow, so editor and CLI builds are identical across
+  // macOS, Windows, and Linux (and GitHub Codespaces).
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "rust-lang.rust-analyzer",
+        "tamasfe.even-better-toml",
+        "vadimcn.vscode-lldb"
+      ],
+      "settings": {
+        "rust-analyzer.check.command": "clippy"
+      }
+    }
+  },
+  // Keep the container running for an attached editor session.
+  "overrideCommand": true
+}

.dockerignore

@@ -0,0 +1,12 @@
+# The dev image bind-mounts the source instead of copying it, so the build
+# context only needs to be small. Keep heavy/host-specific paths out of it.
+.git/
+target/
+**/target/
+**/Cargo.lock.bak
+tests/generated/
+benchmarks/**/target/
+demos/
+*.log
+.DS_Store
+.claude/

Dockerfile

@@ -0,0 +1,58 @@
+# Cross-platform development image for RSScript.
+#
+# The workspace is edition 2024, which requires Rust >= 1.85; `rust:1-bookworm`
+# tracks the latest stable 1.x and always satisfies that. Pin to a concrete tag
+# (e.g. `rust:1.88-bookworm`) if you want a fully reproducible toolchain.
+#
+# The source tree is NOT copied into the image — it is bind-mounted at runtime
+# (see compose.yaml) so edits on the host are seen instantly on every platform.
+# This image only provides the toolchain and system libraries.
+FROM rust:1-bookworm
+
+# System libraries needed to build the workspace and the Rust packages that
+# RSScript lowers to. Everything here uses rustls/ring (no OpenSSL) and a
+# source-bundled SQLite, so the list is just a C/C++ toolchain plus the usual
+# fetch/build helpers:
+#   build-essential, cmake -> `ring` (rustls) and `rusqlite` (bundled SQLite)
+#   pkg-config             -> -sys crate probing
+#   git, curl, ca-certificates -> fetching crates and tools over HTTPS
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        pkg-config \
+        cmake \
+        git \
+        curl \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Toolchain components used by the test/lint flow, and cargo-nextest (the test
+# runner the `rss test` command and CI use). Prefer the prebuilt nextest binary
+# per architecture (works on amd64 and Apple-Silicon/arm64); fall back to a
+# source build on other arches.
+RUN rustup component add clippy rustfmt \
+    && set -eux; \
+    case "$(uname -m)" in \
+        x86_64)  url="https://get.nexte.st/latest/linux" ;; \
+        aarch64) url="https://get.nexte.st/latest/linux-arm" ;; \
+        *)       url="" ;; \
+    esac; \
+    if [ -n "$url" ]; then \
+        curl -LsSf "$url" | tar zxf - -C "${CARGO_HOME:-/usr/local/cargo}/bin"; \
+    else \
+        cargo install cargo-nextest --locked; \
+    fi
+
+# The base image puts the toolchain on PATH via the container environment, but a
+# login shell (`bash -l`, some devcontainer setups) re-derives PATH from
+# /etc/profile and would drop it. Add a profile snippet so cargo/rustc/nextest
+# are on PATH for every shell flavor.
+RUN printf 'export PATH="%s/bin:$PATH"\n' "${CARGO_HOME:-/usr/local/cargo}" \
+        > /etc/profile.d/rust-cargo.sh
+
+WORKDIR /work
+
+# `rss` (and the test suite) compiles generated Rust packages at runtime, so the
+# container keeps the full toolchain available. Default to an interactive shell;
+# compose overrides the command for one-off runs.
+CMD ["bash"]

README.md

@@ -511,6 +511,13 @@ fn main() -> Unit {
 
 Development discipline and the full local verification flow live in [DEVELOPMENT.md](docs/DEVELOPMENT.md): spec prerequisites first, self-hosted validation as the main pressure test, no fixture-only shortcuts, and a broad-first testing loop.
 
+Prefer a containerized toolchain? [DOCKER.md](docs/DOCKER.md) gives an identical, reproducible build/test environment on macOS, Windows, and Linux (and VS Code / Codespaces) with no local Rust install:
+
+```sh
+docker compose build
+docker compose run --rm dev cargo run --bin rss -- test --all
+```
+
 ---
 
 ## Roadmap

compose.yaml

@@ -0,0 +1,37 @@
+# Cross-platform development environment for RSScript.
+#
+# Quick start:
+#   docker compose build                                   # build the dev image
+#   docker compose run --rm dev cargo run --bin rss -- test --all
+#   docker compose run --rm dev bash                       # interactive shell
+#
+# The repo is bind-mounted at /work, so host edits are picked up immediately.
+# Build artifacts and crate caches live in named volumes (not on the bind mount)
+# so compilation persists between runs and stays fast on macOS/Windows.
+services:
+  dev:
+    build: .
+    image: rsscript-dev
+    working_dir: /work
+    volumes:
+      - .:/work
+      # Keep target/ and the cargo caches off the (slow, host-backed) bind mount
+      # and out of the host tree. Mounting only the cache subdirs of CARGO_HOME
+      # preserves the toolchain and nextest installed under /usr/local/cargo/bin.
+      - target:/work/target
+      - cargo-registry:/usr/local/cargo/registry
+      - cargo-git:/usr/local/cargo/git
+    environment:
+      CARGO_TERM_COLOR: always
+      # The workspace target lives in a volume; point every nested build at it
+      # too so generated-package builds share one warm cache.
+      CARGO_HOME: /usr/local/cargo
+    # Keep an interactive TTY for `docker compose run dev bash`.
+    tty: true
+    stdin_open: true
+    command: bash
+
+volumes:
+  target:
+  cargo-registry:
+  cargo-git:

docs/DOCKER.md

@@ -0,0 +1,77 @@
+# Containerized development
+
+RSScript builds and runs identically on macOS, Windows, and Linux through a
+single Docker toolchain image. The container carries the Rust toolchain, the
+test runner, and the system libraries the workspace needs; your checkout is
+bind-mounted in, so edits on the host take effect immediately.
+
+This is the recommended setup for contributors who do not want to install the
+Rust toolchain and C build dependencies locally, and for keeping builds
+reproducible across platforms.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) with Compose v2 (`docker
+  compose`). Docker Desktop (macOS/Windows) or Docker Engine (Linux) both work.
+- That's all — no local Rust, C compiler, or SQLite needed.
+
+## Quick start
+
+```sh
+# Build the dev image (first run downloads the toolchain; later runs are cached).
+docker compose build
+
+# Run the full test suite exactly as CI does.
+docker compose run --rm dev cargo run --bin rss -- test --all
+
+# Open an interactive shell in the toolchain.
+docker compose run --rm dev bash
+```
+
+Inside the shell (or via `docker compose run --rm dev <cmd>`) every normal
+workflow is available:
+
+```sh
+cargo run --bin rss -- test --all          # project test runner (nextest-backed)
+cargo nextest run -p rsscript              # run one crate's tests
+cargo nextest run -p rsscript --features native-jit   # Cranelift JIT tier
+cargo clippy --all-targets                 # lints
+cargo fmt --all                            # format
+cargo run --bin rss -- <args>              # drive the rss CLI
+```
+
+## How it is wired
+
+- **Image** (`Dockerfile`): `rust:1-bookworm` plus `build-essential`, `cmake`,
+  and `pkg-config` (for `ring`/rustls and the bundled-SQLite `rusqlite`),
+  `clippy`/`rustfmt`, and `cargo-nextest`. The workspace uses rustls/ring
+  throughout, so no OpenSSL is required.
+- **Source** is bind-mounted at `/work` (see `compose.yaml`) — not copied into
+  the image — so host edits are picked up with no rebuild.
+- **Caches** live in named volumes, deliberately kept off the host bind mount so
+  compilation persists between runs and stays fast on macOS/Windows:
+  - `target` → `/work/target`
+  - `cargo-registry` → `/usr/local/cargo/registry`
+  - `cargo-git` → `/usr/local/cargo/git`
+
+  Reset a cache with `docker compose down -v` (removes all three volumes).
+
+## Reproducible toolchain
+
+The image tracks the latest stable Rust 1.x (`rust:1-bookworm`), which always
+satisfies the workspace's edition-2024 requirement (Rust ≥ 1.85). For a fully
+pinned toolchain, change the base tag in `Dockerfile` to a concrete version such
+as `rust:1.88-bookworm` and rebuild.
+
+## VS Code / Codespaces
+
+`.devcontainer/devcontainer.json` reuses the same compose service. In VS Code,
+run **Dev Containers: Reopen in Container**; on GitHub, **Create codespace**.
+You get rust-analyzer (clippy-backed), TOML, and LLDB wired to the identical
+toolchain and caches.
+
+## Apple Silicon and other architectures
+
+The image builds natively on both `amd64` and `arm64` (Apple Silicon); the
+nextest install picks the matching prebuilt binary and falls back to a source
+build elsewhere. No extra configuration is needed.

docs/README.md

@@ -13,6 +13,7 @@ LLMs); everything else lives here.
 | [Review_Evidence_IR_Spec_v0.2.md](Review_Evidence_IR_Spec_v0.2.md) | REIR — the review-evidence IR consumed by `--reir` tooling and CI gates. |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Module boundaries of the checker/lowering implementation. |
 | [DEVELOPMENT.md](DEVELOPMENT.md) | Local verification flow and development discipline. |
+| [DOCKER.md](DOCKER.md) | Containerized, cross-platform dev environment (Docker / VS Code / Codespaces). |
 
 ## Implementation-planning specs (not yet normative)