# vera-scheme-sandbox

## Purpose
Provide platform-independent Chez Scheme evaluation for Vera through a WASM runtime, with bounded execution and explicit host-filesystem access modes.

## Registered surface

### Tools
- `scheme_eval` — evaluates R6RS/Chez Scheme code; output is captured from `(display ...)`, `(printf ...)`, stderr, and the tool footer.

### Commands
- none

### Hooks
- `session_start` — verifies the bundled WASM artifacts and warns if integrity checks fail.

## Access modes
- `readonly` (default) mounts the current working directory at `/work` and blocks writes under that mount; process spawning is disabled.
- `write` mounts the current working directory at `/work` with read/write access; process spawning is disabled.
- `fullaccess` mounts the host root filesystem at `/host`, keeps the normal process environment, and enables Chez Scheme `system()`.

## `/work` and `/host`
`/work` is the session working directory projected into the WASM filesystem for `readonly` and `write` runs. Use it for project-local reads, and request `write` only when the Scheme code needs to create or modify files in that working tree.

`/host` is only present in `fullaccess` mode and maps to `/` on the host. Use it only for tasks that genuinely require whole-host paths or `system()`.

## Integrity checks
On `session_start`, the extension computes sha256 hashes for `scheme.js`, `scheme.wasm`, and `scheme.data`. A mismatch, missing file, or unreadable artifact triggers a warning that `scheme_eval` may not work correctly; the tool still registers before the check runs.

## Smoke
- `npm run smoke`
- from package root: `node ./scripts/smoke.mjs`

The smoke script exercises arithmetic, recursion, macros, readonly reads, readonly write blocking, write-mode writes, fullaccess host reads, fullaccess `system()`, and blocked spawning outside fullaccess.

## Intended use cases
- `readonly`: inspect project files, run pure calculations, test Scheme snippets, and do safe read-only analysis.
- `write`: generate or transform project-local files when the requested output should be written under the current working directory.
- `fullaccess`: perform trusted host-level inspection or shell-backed Scheme tasks that cannot be completed through `/work`.

Loaded through `agent/settings.json` as `./packages/vera-scheme-sandbox`.