@daugasauron/dolly-build 0.1.5 → 0.1.6

package/README.md

@@ -1,12 +1,265 @@
-# @daugasauron/dolly-build
+# Dolly from npm
 
-A project with a Dolly image of your own: a Dollyfile `FROM` the installed
-`@daugasauron/dolly-image-pi-minimal` with the packages it INSTALLs (`@daugasauron/dolly-package-NAME`)
-and your files, built in a browser into a site that any static host serves as it lies.
-@daugasauron/dolly's README (`docs/embedding.md`) says how.
+Dolly is a POSIX-like userspace for wasm64 that runs in a browser tab. Its npm
+packages hold the runtime, prebuilt programs and a build command, so a project
+of your own needs no checkout of Dolly: `npm install` is its only download.
+This document is the guide to them. Its main case is a coding agent of your
+own: [Pi](https://github.com/earendil-works/pi) in a sandbox with the tools you
+choose and your skills, served from your machine, and built into the same
+static site in CI. What changed between versions is in the
+[npm changelog](npm-changelog.md), and how to move a project to a new version
+in [Upgrading](npm-upgrading.md).
+
+## A Pi agent of your own
+
+With Node.js 22, npm, Chrome and Python (for its static file server), in an
+empty directory:
 
 ```sh
-npx dolly-build init my-pi git
+npm init --yes
+npm install @daugasauron/dolly-build
+npx dolly-build init my-pi git python nvim
 npx dolly-build Dollyfile-my-pi my-pi
 python3 -m http.server -d my-pi -b 127.0.0.1 8080
 ```
+
+- `init` writes the project: Pi with Git, Python and Neovim here. It installs
+  what the project needs and lacks with npm (the packages named, the host
+  modules they declare), at `dolly-build`'s version, and prints that command.
+- The second `dolly-build` builds the image in a headless browser (45 s for
+  this project on a 16-core desktop) and writes the site `my-pi/` (94 MB).
+- Python's server serves it. Open <http://127.0.0.1:8080/>: Pi asks for your
+  OpenRouter key at a prompt that does not show it, and starts in `/workspace`.
+  `curl https://example.com` in Pi's shell fails: the page's policy admits the
+  model's provider and nothing else. Ctrl+D leaves Pi for a shell. When Pi needs
+  a file of yours it asks with its `upload` tool: the page's file dialog opens,
+  and Pi gets the file's path and size, or that you cancelled. Save
+  (Ctrl+Shift+S) keeps the sandbox, files and all, in this browser and names it
+  in the address (`?session=NAME`), which opens it again as it was.
+
+After `npm install` and `init`, nothing is downloaded: the build, its browser,
+the site and its page fetch from `node_modules` and from each other alone. The
+build's browser reaches only a server the command runs on 127.0.0.1; its own
+requests (its vendor's updates, clock and autofill) go to a proxy of the
+command's that refuses them.
+
+## The project
+
+| File | What it declares | After a change |
+| --- | --- | --- |
+| `Dollyfile-my-pi` | The sandbox, a [recipe](dollyfile.md): `INSTALL` rows for Pi's packages and the ones you named, each pinned by its recipe's SHA-256; `FILE` rows with Pi's `AGENTS.md`, an extension with a `/hello` command, a `todo` tool, the model's entry and the script that starts Pi with its provider and model | Build again |
+| `public/skills/` | Pi's skills, one directory each: a `SKILL.md` and the files it names. The page writes them into `~/.pi/agent/skills/` at each boot | Build again (the image is kept) |
+| `public/workspace/` | The project the agent works on, written into `/workspace` at each boot | Build again (the image is kept) |
+| `public/main.mjs` | The hosts the agent may reach ([HTTP policy](http.md)): one rule per host, OpenRouter's API to begin with. The files the page writes at boot | Build again (the image is kept) |
+| `public/index.html`, `public/page.css`, `public/icon.svg` | The page, and the popups' font. No inline script or style, so the host may serve a strict Content-Security-Policy ([Embedding](embedding.md)) | Build again (the image is kept) |
+| `public/theme.json` | The sandbox's colours: five values in Pi's theme format, whose background, text, accent and muted are the terminal's and the popups' too | Build again (the image is kept) |
+| `.github/workflows/my-pi.yml` | The same build in GitHub Actions ([CI](#ci)) | |
+| `package.json`, `package-lock.json` | The packages, at exact versions | `npm install` |
+| `my-pi/` | The site `dolly-build` writes, which `.gitignore` leaves out | Reload |
+
+A build that keeps the image takes seconds: the image is built again only when
+the recipe or the installed runtime changed.
+
+## Tools
+
+A tool is a package: a program built inside Dolly from its upstream source,
+with the packages it needs. `init` takes the ones to start with, and `add`
+puts more into the recipe of a project, installing them first:
+
+```sh
+npx dolly-build add my-pi jq sqlite
+```
+
+| Package | What it brings |
+| --- | --- |
+| `git` | Git over the page's HTTP broker, with `diff` and `patch` |
+| `python` | CPython 3.14 with pip; it brings `cc` and `libffi` |
+| `numpy`, `pandas`, `matplotlib`, `seaborn`, `python-dateutil` | Python's data libraries, each with the ones it needs and `python` |
+| `nvim` | Neovim, with its runtime files and tree-sitter parsers |
+| `cc` | The C and C++ compiler, with `ld`, `ar`, Make and the headers |
+| `jq`, `sqlite`, `less` | `jq`, `sqlite3` and the pager |
+| Pi's own, which `init` always installs | `core` (the shell `slop` and its commands), `posix` (grep, sed, awk, find and the others), `curl`, `display` (the terminal), `dollyfile` (the recipe engine) and `pi-dolly` (Pi, its JavaScript runtime, ripgrep, fd, the `download` and `upload` commands, and Pi's Dolly skill and tools, among them `download` and `upload`, which hand the user a file and ask the user for one) |
+
+`npx dolly-build init` with a name that is no package lists them all. A program
+that is not among them is built in the recipe, where a compiler is: a `FILE`
+row with a C source and `SLOP cc /tmp/NAME.c -o /usr/bin/NAME`, or
+`SLOP pip install NAME==VERSION` followed by `FOLDER
+/usr/lib/python3.14/site-packages`, which keeps what pip installed (pure-Python
+wheels and sdists install). A script is a `FILE` row under `/usr/bin` with
+`EXPORTS TOOL NAME`, as the template's `todo` is. The recipe's comments show
+each.
+
+A package declares the host modules its programs need (`python` declares
+`sockets`), and a recipe's `REQUIRES HOST` rows must name them: `init` and
+`add` write those rows and install the modules' packages
+(`@daugasauron/dolly-host-NAME`). The site holds the modules its recipe
+declares and no other.
+
+## Skills and instructions
+
+- A skill is a directory under `public/skills/` with a `SKILL.md`: front matter
+  with its `name` and `description`, then what the agent does when a task
+  matches the description (Pi's `docs/skills.md`, in the image under
+  `/usr/lib/node_modules/@earendil-works/pi-coding-agent/docs/`). Scripts and
+  other files a skill names lie beside it and are at
+  `~/.pi/agent/skills/NAME/` in the sandbox. Pi lists the skills when it
+  starts. `init` writes one, `changelog`.
+- `AGENTS.md`, the instructions Pi takes into every session, is a `FILE` row of
+  the recipe; so are an extension (`/hello`), the model's entry
+  (`models.json`) and the script that starts Pi (`/etc/dolly/init.slop`).
+  [An agent in place of a web frontend](agent-frontend.md) goes on from here:
+  your backend's API, another model provider, how Pi starts.
+- These files are not secrets: Pi's tools can read them, and so can its model.
+
+## The policy and the key
+
+`public/main.mjs` holds the page's HTTP policy: the hosts the sandbox may
+reach, one rule each, with the header that may carry a credential. It is
+enforced in the browser, outside the sandbox ([HTTP](http.md)). `init` writes
+one rule, OpenRouter's API, and Anthropic's as a comment beside it. The key is
+typed at `pi-key`'s prompt in the sandbox each time it starts; it is in no
+file of the site. A host the agent should reach (`api.github.com`, `pypi.org`)
+is one more rule.
+
+## Build
+
+`dolly-build Dollyfile-NAME OUT` writes the site `OUT`, replacing the one it
+wrote there before: the files of `public/`, `workspace.json` and `skills.json`
+(the files under `public/workspace/` and `public/skills/`), the runtime
+(`dolly/`), the device host modules the recipe declares (`dolly-host-NAME/`),
+`coi-serviceworker.js` and `image/`, the image's directory (its catalog,
+metadata and packs, the recipes it was built from, its `amy-index.txt` and an
+`index.mjs`).
+
+- The build runs in a browser, with the installed runtime's own builder.
+  Without `--browser` it takes the first this machine has of Chrome, Playwright's
+  Chromium and Playwright's Firefox; `--browser chrome`, `chromium` or `firefox`
+  names one (`npx playwright-core install chromium-headless-shell` or `firefox`
+  installs Playwright's). It needs Chrome 138 or Firefox 146 or later, as the
+  page does.
+- Both commands run in the directory whose `node_modules/@daugasauron/` holds
+  the packages (npm, pnpm and Yarn 1 alike; Yarn 2 and later need `nodeLinker:
+  node-modules`). `init` and `add` install with the package manager that runs
+  them (`npm install`, `pnpm add` or `yarn add`); their install is measured
+  with npm alone.
+- A recipe's steps reach the network only where the recipe says so: a `SOURCE`
+  row, or a `SLOP` step such as `pip install`. The browser hands each such
+  request to `dolly-build`, which fetches it in Node, so a host without CORS
+  headers works, and through the proxy `HTTPS_PROXY` or `HTTP_PROXY` names; the
+  log names each host a build reaches. What a step fetches is not part of the
+  image's identity: pin versions (`pip install NAME==1.2`) where the bytes
+  matter. `init`'s recipe has no such step.
+- A recipe is at most 128 KiB. A `FILE` under `/workspace` is part of the
+  image; the page's `public/workspace/` is written over it at each fresh boot.
+
+## CI
+
+`init` writes `.github/workflows/my-pi.yml`: on a push to `main`, a pull
+request or by hand, it checks the project out, runs `npm ci`, installs
+Playwright's headless Chromium (the version `package-lock.json` pins, with the
+system libraries it needs), builds the site with it and uploads it as the
+artifact `github-pages`:
+
+```yaml
+      - run: npm ci
+      - run: npx playwright-core install --with-deps chromium-headless-shell
+      - run: npx dolly-build Dollyfile-my-pi my-pi --browser chromium
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: my-pi
+```
+
+Commit the project as `init` left it (`package-lock.json` too; `.gitignore`
+leaves out `node_modules/` and the site). The file ends with a `deploy` job as
+comments, which publishes the site on GitHub Pages once the repository's
+Pages source is "GitHub Actions". Pages sends no isolation headers; the page
+isolates itself ([Serving](#serving)).
+
+Elsewhere the same three commands are the job. In Playwright's container image
+of the version of `playwright-core` the lockfile holds
+(`mcr.microsoft.com/playwright:vVERSION-noble`), the browser is there already.
+After `npm ci` and the browser, a CI build downloads nothing either.
+`PLAYWRIGHT_DOWNLOAD_HOST` points the browser's download at a mirror.
+
+How this is checked: `test/npm-browser.mjs` commits the project `init` wrote,
+clones it, and runs the workflow's own `npm ci` and build lines in the clone,
+in a network namespace whose only network is loopback, with Chrome and with
+Firefox; the site's image is the one the project built. The workflow file has
+not been run on GitHub's runners by Dolly's tests.
+
+## Serving
+
+The site is static: any file server serves it as it lies, from any path.
+
+- Dolly needs shared memory, which a browser gives only to a cross-origin
+  isolated page. Where the host sends `Cross-Origin-Opener-Policy: same-origin`
+  and `Cross-Origin-Embedder-Policy: require-corp`, the page is isolated. Where
+  it does not (Python's server, GitHub Pages), `init`'s page registers
+  `coi-serviceworker.js`, which adds them to the site's own responses, and
+  loads once more under it. A service worker needs HTTPS or `127.0.0.1`.
+- The host must serve `.wasm` as `application/wasm`, `.mjs` as
+  `text/javascript` and `.json` as `application/json`.
+- The image's packs stay in the origin's private storage after the first
+  visit, so the page starts again without downloading them.
+
+## Updating
+
+The packages of one project are of one version: `init` and `add` install at
+`dolly-build`'s, and a build with two versions fails, naming both. To move a
+project to a new version, install `dolly-build` at it; `add` then installs the
+project's other packages at that version and writes the recipe's pins again:
+
+```sh
+npm install --save-exact @daugasauron/dolly-build@0.1.7
+npx dolly-build add my-pi
+npx dolly-build Dollyfile-my-pi my-pi
+```
+
+`add` writes every `FROM` and `INSTALL` row at the pin of the installed
+package that holds its recipe. A row whose pin no installed package holds
+fails the build, naming the row.
+
+## The packages
+
+| Package | What it holds |
+| --- | --- |
+| `@daugasauron/dolly-build` | The `dolly-build` command. It depends on the runtime, on `playwright-core`, which starts the build's browser, and on Pi's packages |
+| `@daugasauron/dolly` | The runtime: `boot()`, the kernel, the process runtime, the image builder, and the host modules that are its own machinery ([Embedding](embedding.md)) |
+| `@daugasauron/dolly-host-NAME` | One device host module each: `display`, `input`, `html`, `sockets`, `gpu`, `audio`, `microphone`, `touch`, `clipboard`, `upload`, `pty`, `console`, and `save`, which is `download@0` (npm takes no new name with that word) |
+| `@daugasauron/dolly-package-NAME` | A package for a recipe to `INSTALL` ([Tools](#tools)): its catalog, metadata, packs and recipes. It depends on the packages it installs, so npm brings them |
+| `@daugasauron/dolly-image-NAME` | A whole image for `boot()`: `default` (a shell and its tools), `pi-minimal` (Pi alone) and `python-data` (Python with NumPy, pandas, Matplotlib and seaborn) |
+
+Each host module and image depends on the runtime alone. An image or package
+does not depend on the host modules it declares: the page chooses its modules.
+
+## A recipe on an image
+
+A recipe may start `FROM` an installed image instead of installing packages:
+the image package's README gives the row. `FROM` carries the base's files,
+environment and exports but not its host modules or `ENTRY`, so the recipe
+repeats those. `init` writes Pi's project only; the page in `public/` is then
+[Embedding](embedding.md)'s, importing `./dolly/page/browser.mjs` and
+`./image/index.mjs`, with the lines of `init`'s `main.mjs` that register
+`coi-serviceworker.js`.
+
+```sh
+npm install @daugasauron/dolly-build   # with the install line of the image package's README
+npx dolly-build Dollyfile-my-data my-data
+```
+
+To run a prebuilt image in a page with no build at all, see
+[Embedding](embedding.md).
+
+## When something fails
+
+| Message | What to do |
+| --- | --- |
+| `NAME: no such package. The packages: …` | `init` and `add` take the names listed |
+| `that install failed` | Run the printed `npm install` line yourself (a registry or proxy setting), then the command again |
+| `no installed package holds … at that pin` | The packages were updated: `npx dolly-build add NAME` |
+| `… holds X at another pin than …: install packages of one version` | Install every `@daugasauron` package at one version ([Updating](#updating)) |
+| `NAME declares sockets: install @daugasauron/dolly-host-sockets` | A `REQUIRES HOST` row written by hand names a module that is not installed |
+| `a browser is not installed` | Install Chrome, or `npx playwright-core install chromium-headless-shell` |
+| `this browser has no WebAssembly memory64` | The build's browser is older than Chrome 138 or Firefox 146 |
+| `Dollyfile-NAME:LINE: unknown directive` | A `FILE` row's body lines start with four spaces |
+| The page says it is not cross-origin isolated | It is served over plain HTTP from another address than `127.0.0.1`: serve it over HTTPS, or send the two headers |

package/host/requirements.mjs

@@ -1,6 +1,6 @@
 import { DOLLY_HOST_RECORD_BYTES as recordBytes, DOLLY_HOST_NAME_BYTES as nameBytes,
   DOLLY_HOST_DIGEST_BYTES as digestBytes, DOLLY_HOST_MAX_RECORDS as maxRecords } from "./abi.mjs";
-import { hex } from "../src/static-asset.mjs";
+import { hex } from "../page/static-asset.mjs";
 
 const pattern = /^([a-z][a-z0-9-]{0,30})@(0|[1-9][0-9]{0,4})$/;
 

package/host/runtime/abi.mjs

@@ -0,0 +1,41 @@
+// Generated from abi/dolly-supervisor-0.wat, abi/dolly-image-0.wat, abi/dolly-process-0.wat, abi/dolly-process-gate-0.wat, include/dolly/process.h.
+export const DOLLY_PROCESS_EVENT_LAUNCH = 1;
+export const DOLLY_PROCESS_EVENT_INTERRUPT = 2;
+export const DOLLY_PROCESS_EVENT_TERMINATE = 3;
+export const DOLLY_PROCESS_EVENT_WAKE = 4;
+export const DOLLY_PROCESS_EVENT_KIND_SHIFT = 48;
+export const DOLLY_PROCESS_EVENT_VALUE_SHIFT = 32;
+export const DOLLY_TERMINAL_WORD_RESULT_SEQUENCE = 0;
+export const DOLLY_TERMINAL_WORD_RESULT_STATUS = 1;
+export const DOLLY_TERMINAL_WORD_FOREGROUND_PID = 2;
+export const DOLLY_TERMINAL_WORD_FOREGROUND_INTERRUPTIBLE = 3;
+export const DOLLY_TERMINAL_WORD_INTERRUPT_SEQUENCE = 4;
+export const DOLLY_TERMINAL_WORD_INTERRUPT_TARGET_PID = 5;
+export const DOLLY_FS_BLOCK_SIZE = 1048576;
+export const DOLLY_DEVICE_HEADER_BYTES = 32;
+export const DOLLY_DEVICE_REPLY_HEADER_BYTES = 64;
+export const DOLLY_DEVICE_REPLY_WORD_STATE = 0;
+export const DOLLY_DEVICE_REPLY_WORD_SCOPE = 1;
+export const DOLLY_DEVICE_REPLY_WORD_SEQUENCE = 2;
+export const DOLLY_DEVICE_REPLY_WORD_ERRNO = 3;
+export const DOLLY_DEVICE_REPLY_WORD_LENGTH = 4;
+export const DOLLY_DEVICE_REPLY_PUBLISHED = 1;
+export const DOLLY_SNAPSHOT_VERSION = 2;
+export const DOLLY_SNAPSHOT_HEADER_BYTES = 16;
+export const DOLLY_SNAPSHOT_RECORD_HEADER_BYTES = 16;
+export const DOLLY_SNAPSHOT_RECORD_DIRECTORY = 1;
+export const DOLLY_SNAPSHOT_RECORD_FILE = 2;
+export const DOLLY_SNAPSHOT_RECORD_SYMLINK = 3;
+export const DOLLY_SNAPSHOT_RECORD_DELETED = 4;
+export const DOLLY_SNAPSHOT_MAX_PATHS = 100000;
+export const DOLLY_SNAPSHOT_MAX_MEBIBYTES = 2048;
+export const DOLLY_SNAPSHOT_PATH_MIN_BYTES = 2;
+export const DOLLY_SNAPSHOT_PATH_MAX_BYTES = 4095;
+export const DOLLY_SNAPSHOT_SYMLINK_MIN_BYTES = 1;
+export const DOLLY_SNAPSHOT_SYMLINK_MAX_BYTES = 4095;
+export const DOLLY_ENTRY_VERSION = 1;
+export const DOLLY_ENTRY_HEADER_BYTES = 16;
+export const DOLLY_ENTRY_MAX_ARGUMENTS = 256;
+export const DOLLY_ENTRY_ARGUMENT_MAX_BYTES = 4096;
+export const DOLLY_ENTRY_MAX_BYTES = 65536;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "name": "@daugasauron/dolly-build",
   "license": "MIT",
@@ -7,10 +7,16 @@
     "dolly-build": "scripts/dolly-build.mjs"
   },
   "dependencies": {
-    "@daugasauron/dolly": "0.1.5",
-    "playwright-core": "1.63.0"
+    "@daugasauron/dolly": "0.1.6",
+    "playwright-core": "1.63.0",
+    "@daugasauron/dolly-package-core": "0.1.6",
+    "@daugasauron/dolly-package-dollyfile": "0.1.6",
+    "@daugasauron/dolly-package-posix": "0.1.6",
+    "@daugasauron/dolly-package-display": "0.1.6",
+    "@daugasauron/dolly-package-curl": "0.1.6",
+    "@daugasauron/dolly-package-pi-dolly": "0.1.6"
   },
-  "description": "Build a Dolly image of your own, FROM an installed image package, in a browser, into a static site.",
+  "description": "Build a Dolly image of your own from installed packages, in a browser, into a static site.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/daugasauron/dolly.git"

package/packages.json

@@ -0,0 +1,101 @@
+{
+ "packages": {
+  "cc": [],
+  "core": [],
+  "curl": [],
+  "display": [
+   "display"
+  ],
+  "dolly-docs": [],
+  "dollyfile": [],
+  "fd": [],
+  "git": [],
+  "gzip": [],
+  "html": [
+   "html"
+  ],
+  "janis": [
+   "download"
+  ],
+  "janis-install": [
+   "download"
+  ],
+  "jq": [],
+  "less": [],
+  "libdolly-audio": [],
+  "libdolly-clipboard": [],
+  "libdolly-display": [],
+  "libdolly-download": [],
+  "libdolly-gpu": [],
+  "libdolly-input": [],
+  "libdolly-microphone": [],
+  "libdolly-nena": [],
+  "libdolly-packages": [],
+  "libdolly-pty": [],
+  "libdolly-sockets": [],
+  "libdolly-threads": [],
+  "libdolly-touch": [],
+  "libdolly-upload": [],
+  "libffi": [],
+  "matplotlib": [
+   "sockets"
+  ],
+  "numpy": [
+   "sockets"
+  ],
+  "nvim": [],
+  "pandas": [
+   "sockets"
+  ],
+  "pi": [
+   "download"
+  ],
+  "pi-dolly": [
+   "download",
+   "html",
+   "upload"
+  ],
+  "posix": [],
+  "python": [
+   "sockets"
+  ],
+  "python-dateutil": [
+   "sockets"
+  ],
+  "quickjs": [],
+  "ripgrep": [],
+  "sbase": [],
+  "seaborn": [
+   "sockets"
+  ],
+  "secretenv": [],
+  "sqlite": [],
+  "transfer": [
+   "download",
+   "upload"
+  ]
+ },
+ "images": {
+  "default": [
+   "display",
+   "download",
+   "input",
+   "upload"
+  ],
+  "pi-minimal": [
+   "display",
+   "download",
+   "html",
+   "input",
+   "upload"
+  ],
+  "python-data": [
+   "display",
+   "download",
+   "html",
+   "input",
+   "sockets",
+   "upload"
+  ]
+ }
+}

package/{src → page}/image-entry.mjs

@@ -1,22 +1,26 @@
-// Shared by packaging and browser admission; empty arguments are valid.
+import { DOLLY_ENTRY_VERSION, DOLLY_ENTRY_HEADER_BYTES, DOLLY_ENTRY_MAX_ARGUMENTS, DOLLY_ENTRY_ARGUMENT_MAX_BYTES,
+  DOLLY_ENTRY_MAX_BYTES } from "../host/runtime/abi.mjs";
+
+// /etc/dolly/entry, as abi/dolly-image-0.wat lays it out. Shared by packaging and
+// browser admission; empty arguments are valid.
 export function decodeImageEntry(bytes) {
-  if (!(bytes instanceof Uint8Array) || bytes.byteLength < 16 || bytes.byteLength > 64 * 1024) {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength < DOLLY_ENTRY_HEADER_BYTES || bytes.byteLength > DOLLY_ENTRY_MAX_BYTES) {
     throw new TypeError("invalid image ENTRY record");
   }
   const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (decoder.decode(bytes.subarray(0, 8)) !== "DOLLYENT" || view.getUint32(8, true) !== 1) {
+  if (decoder.decode(bytes.subarray(0, 8)) !== "DOLLYENT" || view.getUint32(8, true) !== DOLLY_ENTRY_VERSION) {
     throw new TypeError("invalid image ENTRY version");
   }
   const count = view.getUint32(12, true);
-  if (count === 0 || count > 256) throw new TypeError("invalid image ENTRY count");
-  let offset = 16;
+  if (count === 0 || count > DOLLY_ENTRY_MAX_ARGUMENTS) throw new TypeError("invalid image ENTRY count");
+  let offset = DOLLY_ENTRY_HEADER_BYTES;
   const arguments_ = [];
   for (let index = 0; index < count; ++index) {
     if (offset > bytes.byteLength - 4) throw new TypeError("truncated image ENTRY");
     const size = view.getUint32(offset, true);
     offset += 4;
-    if (size > 4096 || offset > bytes.byteLength - size) throw new TypeError("invalid image ENTRY argument");
+    if (size > DOLLY_ENTRY_ARGUMENT_MAX_BYTES || offset > bytes.byteLength - size) throw new TypeError("invalid image ENTRY argument");
     const value = decoder.decode(bytes.subarray(offset, offset + size));
     if (value.includes("\0")) throw new TypeError("image ENTRY has a NUL argument");
     arguments_.push(value);

package/{src → page}/image-inputs.mjs

@@ -1,3 +1,5 @@
+import { Sha256 } from "./sha256.mjs";
+
 // Recipe pins identify instructions; artifact digests identify their results.
 export function imageInputs(artifacts = []) {
   if (!Array.isArray(artifacts) || artifacts.length > 256) throw new Error("invalid image inputs");
@@ -18,3 +20,12 @@ export function imageInputs(artifacts = []) {
 export function imageInputsMatch(actual, expected) {
   return JSON.stringify(imageInputs(actual)) === JSON.stringify(imageInputs(expected));
 }
+
+// The catalog's digest of an image's recipe records (its metadata's recipes),
+// one line each, "SHA256 BYTES PATH\n", in their order: a start checks the
+// records against the catalog without the catalog repeating them.
+export function recipesDigest(recipes) {
+  const hash = new Sha256();
+  hash.update(new TextEncoder().encode(recipes.map(({ sha256, byteLength, sourcePath }) => `${sha256} ${byteLength} ${sourcePath}\n`).join("")));
+  return hash.hex();
+}

package/{src → page}/image-names.mjs

@@ -5,7 +5,7 @@
 // Dollyfile-example.txt is never a recipe.
 export const validName = name => /^[a-z][a-z0-9]*(?:-[a-z0-9]+|\.[0-9]+)*$/.test(name) && name.length <= 32;
 
-// No image retains scratch space.
+// No image retains scratch space, /tmp.
 export function unretainedPath(value) {
-  return ["/tmp", "/workspace"].some((prefix) => value === prefix || value.startsWith(`${prefix}/`));
+  return value === "/tmp" || value.startsWith("/tmp/");
 }

package/page/sha256.mjs

@@ -0,0 +1,65 @@
+// SHA-256 over bytes given in pieces, for a digest of more bytes than the page
+// should hold at once; WebCrypto digests only a whole buffer.
+const K = Int32Array.of(
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2);
+
+export class Sha256 {
+  state = Int32Array.of(0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19);
+  block = new Uint8Array(64);
+  used = 0;
+  length = 0;
+  words = new Int32Array(64);
+
+  compress(view, offset) {
+    const w = this.words, s = this.state;
+    for (let i = 0; i < 16; i++) w[i] = view.getInt32(offset + 4 * i);
+    for (let i = 16; i < 64; i++) {
+      const x = w[i - 15], y = w[i - 2];
+      w[i] = (((x >>> 7 | x << 25) ^ (x >>> 18 | x << 14) ^ x >>> 3) + w[i - 7] +
+        ((y >>> 17 | y << 15) ^ (y >>> 19 | y << 13) ^ y >>> 10) + w[i - 16]) | 0;
+    }
+    let a = s[0], b = s[1], c = s[2], d = s[3], e = s[4], f = s[5], g = s[6], h = s[7];
+    for (let i = 0; i < 64; i++) {
+      const t1 = (h + ((e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7)) + (e & f ^ ~e & g) + K[i] + w[i]) | 0;
+      const t2 = (((a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10)) + (a & b ^ a & c ^ b & c)) | 0;
+      h = g; g = f; f = e; e = (d + t1) | 0; d = c; c = b; b = a; a = (t1 + t2) | 0;
+    }
+    s[0] += a; s[1] += b; s[2] += c; s[3] += d; s[4] += e; s[5] += f; s[6] += g; s[7] += h;
+  }
+
+  update(bytes) {
+    this.length += bytes.length;
+    let offset = 0;
+    if (this.used !== 0) {
+      offset = Math.min(64 - this.used, bytes.length);
+      this.block.set(bytes.subarray(0, offset), this.used);
+      this.used += offset;
+      if (this.used < 64) return;
+      this.compress(new DataView(this.block.buffer), 0);
+      this.used = 0;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    for (; offset + 64 <= bytes.length; offset += 64) this.compress(view, offset);
+    this.block.set(bytes.subarray(offset));
+    this.used = bytes.length - offset;
+  }
+
+  // The lowercase hex digest; the hash takes no more bytes after it.
+  hex() {
+    const bits = this.length * 8;
+    this.update(Uint8Array.of(0x80));
+    this.update(new Uint8Array((120 - this.used) % 64));
+    const view = new DataView(this.block.buffer);
+    view.setUint32(56, Math.floor(bits / 2 ** 32));
+    view.setUint32(60, bits >>> 0);
+    this.compress(view, 0);
+    return [...this.state].map(word => (word >>> 0).toString(16).padStart(8, "0")).join("");
+  }
+}