diff --git a/AGENTS.md b/AGENTS.md index 3bea3e6..d36451f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ make build APP= # one module into build/.wasm make run APP= # build, then both passes against fixtures/ make run APP= FIXTURES=fixtures/no-call make run APP= FIXTURES=fixtures/unanswered -tools/check.sh # what CI runs: links, builds, runs, ports +sh tools/check.sh # what CI runs: links, builds, runs, ports ``` `make run` mounts only the paths an app's manifest declares, read-only, and @@ -35,8 +35,9 @@ stops before its run pass there, which is expected. genotype can take are in `docs/04-reading-data.md`. - Nothing in the sandbox is random or timed. Sort anything you list. - Keep the module small. Rust apps carry the release profile from any sibling's - `Cargo.toml`. -- Run `tools/check.sh` before proposing a change. New fixtures follow + `Cargo.toml`, and commit their own `Cargo.lock`, since the build runs with + `--locked`. One plain `cargo build` in the app's folder writes it. +- Run `sh tools/check.sh` before proposing a change. New fixtures follow `fixtures/README.md`, with no trailing newline in any value file. ## The report diff --git a/README.md b/README.md index f3f4be2..1ad47c1 100644 --- a/README.md +++ b/README.md @@ -58,14 +58,16 @@ ark data paths # what apps can read on this Ark ark app run build/01-hello-rust.wasm > report.md ``` -Scripts and AI agents driving an Ark read `ark help agents` first. +AI agents driving an Ark read `ark help agents` first. [docs/05-running.md](docs/05-running.md) covers the toolchains, the fixtures, what a laptop can't reproduce, and running on an Ark or an emulator. ## The examples Most data comes in two versions. A *mini* shows the bare read in a few lines, -and a full app turns the same read into a report. +and a full app turns the same read into a report. Each row is a folder under +`apps/`, with the language appended for the minis, such as +`03-cilantro-mini-rust`, and that folder name is what `APP=` takes. | App | What it shows | Languages | | :-- | :-- | :-- | diff --git a/docs/05-running.md b/docs/05-running.md index 611c10e..16d3bb8 100644 --- a/docs/05-running.md +++ b/docs/05-running.md @@ -63,6 +63,11 @@ from the fixture root, read-only, and runs the module again with `/` as its first argument. An undeclared path is never mounted, which is how [02-permissions](../apps/02-permissions) can show a blocked read on a laptop. +An app kept outside this repository runs against these fixtures the same way, +since `tools/run.sh` takes any module, as in +`sh tools/run.sh path/to/app.wasm fixtures`. Build it with the `wasm-opt` +feature flags in `tools/build.sh`, because an Ark's runtime accepts only those. + ### Small modules An Ark uploads and starts a smaller module faster, so every build here is tuned @@ -132,5 +137,5 @@ ark app run build/03-cilantro-mini-rust.wasm > report.md `ark app run` uploads the module and waits while the owner approves it on their phone. It then writes the report to standard output. A refused app comes back with the reason. `ark help apps` covers manifests and grants, and -`ark help datasets` covers the data commands. Scripts and AI agents read -`ark help agents` first, and `ark-emulator help agents` for the emulator. +`ark help datasets` covers the data commands. AI agents read `ark help agents` +first, and `ark-emulator help agents` for the emulator. diff --git a/tools/run.sh b/tools/run.sh index 9f9d839..8a210d2 100644 --- a/tools/run.sh +++ b/tools/run.sh @@ -17,14 +17,21 @@ printf '%s\n' "$manifest" # Mount only the datasets the manifest declares, each at its own path, so the app # sees exactly what it asked for and nothing else, like the device does. +# wasmtime lets a guest write to every directory it mounts, so the datasets are +# copied into a scratch tree without write permission and mounted from there. +stage="$(mktemp -d)" +trap 'chmod -R u+w "$stage"; rm -rf "$stage"' EXIT set -- for dataset in $(printf '%s\n' "$manifest" | grep -oE '"v1/[^"]*"' | tr -d '"'); do if [ ! -d "$fixtures/$dataset" ]; then printf 'fixture root has no declared dataset: %s\n' "$dataset" >&2 exit 1 fi - set -- "$@" --dir "$fixtures/$dataset::/$dataset" + mkdir -p "$stage/$(dirname "$dataset")" + cp -R "$fixtures/$dataset" "$stage/$dataset" + set -- "$@" --dir "$stage/$dataset::/$dataset" done +chmod -R a-w "$stage" echo echo "== run pass =="