prolog-notebook 0.1.2 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,216 @@
 # Changelog
 
+## [0.3.1] — 2026-08-30
+
+### Changed
+
+- **The build line in `--version` carries one date, and it is the build's.**
+
+      Built from commit ca69c2a on 2026-08-30 14:42:46 UTC
+      Working copy ca69c2a (modified)
+
+  The commit's own date is gone: the hash already identifies it, and anyone who wants it can
+  ask git. A working copy now carries no date at all, which follows from the same rule rather
+  than being a separate decision — the only date left is the build's, and a working copy has
+  not been built. UTC, to the second, because a build stamp is read by whoever is holding the
+  package, wherever they are.
+
+## [0.3.0] — 2026-08-30
+
+**A chapter is a file you can read, run, and fill in from the command line.** The renderer,
+the page's own behaviour, and the first half of the CLI.
+
+### Why
+
+0.2.0 made a `.prolog.md` executable. It did not make one *publishable*: the answers a chapter
+shows had to be typed by its author, which means they were the author's guess at what SWI
+prints, published as though it ran. Everything here follows from closing that gap and from
+what the closing revealed.
+
+`prolog-notebook run` now fills a chapter's answers in from a real engine. Run against the
+chapter in this repository it changes nothing — the hand-written answers were already exactly
+what SWI produces, hashes included, which is now a test.
+
+### Added
+
+- **`prolog-notebook run <file>…`** — consults every program cell, runs every query below it,
+  and writes the solution sequences back with an `input-hash` for each. `--limit`, `--stdout`,
+  `--quiet`. The logic is in `src/run.js` and takes a parsed notebook and a session, so
+  `--check` and a VS Code "run all" will get the same behaviour without a shell.
+- **`--version`**, which says which SWI-Prolog will produce your answers. swipl-wasm 8.0.7
+  ships SWI-Prolog 10.1.13, and the two numbers are unrelated — so the engine version is the
+  one fact there that nobody could have looked up. A published install also reports the commit
+  it was built from; a working copy says so, and says when it has uncommitted edits.
+- **A chapter is readable cold.** Saved answers render with no engine anywhere, and are marked
+  stale when the program above them has moved.
+- **`hold`** — a query cell can withhold its saved answers until the reader runs it, or until
+  they have written the prediction above it. A page that has already printed all six answers is
+  arguing with prose that says "press Run".
+- **`rerun="auto"`** — the answers follow the program. On consult, never on edit; never
+  starting work nobody asked for; and a held cell stays manual until its wait ends.
+- **The page's own controls**: a lozenge that raises a card — what the engine is holding, the
+  chapter's answers shown or hidden, and the notebook itself. It says which version is on
+  screen, and once the two differ, lets you download either.
+- **Per-cell reset**, on both runnable kinds. On a program cell that means out of the engine
+  as well as back to the chapter's text.
+- **A stateful cell says so** before anything is asserted into it.
+- **Download your own copy** — the reader leaves with a real `.prolog.md`, their edits and
+  their answers in it, hashed against the program that produced them.
+
+### Fixed
+
+- **An answer containing variables was not what SWI would print.** `app([1,2], Tail, L)` came
+  out as `L = [1,2|_20306],  Tail = _20428` where a toplevel prints `L = [1, 2|Tail]` — the
+  same variable shown as two, with the reader's own name for it discarded. Each binding was
+  rendered in a separate round trip into Prolog, and two round trips cannot share a variable.
+  Prolog now renders the whole answer, once, with the goal's own `variable_names`. Invisible
+  until now because every answer in the shipped chapter is a ground atom.
+- **A half-walked query was destroyed by running any other cell.** SWI keeps open queries on a
+  stack; nothing here released one, and the next query nested inside it. There is now one open
+  sequence per engine, and the cell that loses its own is told so in words about the notebook
+  rather than about SWI's internals.
+- **A `hold` release, a stuck Hide control, and a panel that resized under the cursor** — all
+  found by reading the page rather than the tests, which is why `src/notebook.js` now has a
+  jsdom harness and the page's behaviour is asserted from Node.
+- **A compile error is reported in the cell's own terms**, not as a path the reader never
+  chose.
+
+### Changed
+
+- **The engine is pinned exactly** (`swipl-wasm 8.0.7`). Two installs of one release, ten
+  minutes apart, ran SWI-Prolog 10.1.10 and 10.1.13 — and a chapter's saved answers are only
+  ever true of the engine that produced them. Moving the engine is now a commit with the
+  chapters re-run in it.
+- Solutions are spelled as SWI's own writer spells them, so compounds gain a space after each
+  comma: `foo(1, 2)`, not `foo(1,2)`. Any file with saved answers containing a compound will
+  differ on its next `run`.
+- `offerDownload()` takes an options object rather than positional arguments.
+- The engine is imported where it is used rather than at the top of the CLI, so `--help` still
+  works on an install whose WebAssembly is missing.
+
+### Notes
+
+`--check` — run a chapter in CI and fail the build when its answers have drifted — is
+deliberately **not** here. It needs a timeout first: the Node engine runs in-process, so a
+non-terminating goal hangs the command, and a test suite that can hang forever is not a test
+suite. The command says so on every run.
+
+## [0.2.0] — 2026-08-16
+
+**Breaking: the session API is asynchronous.** `consult`, `next` and `all` now return
+promises, and in the browser the engine runs in a Web Worker.
+
+### Why
+
+A Prolog query is synchronous WASM, so a goal that never terminates blocks the thread it
+runs on. Measured, not assumed: `consult('loop :- loop.')` followed by `query('loop').next()`
+stopped Node's event loop dead — a timer scheduled for 3 seconds never fired. In a browser
+that is not a slow page, it is a dead one: no repaint, no button, no way back except closing
+the tab.
+
+That is unacceptable here specifically, because **non-termination is chapter material**. Left
+recursion and a generator with no base case are things a Prolog book has to demonstrate, and
+the demonstration has to be survivable.
+
+### Added
+
+- **The page says what the engine is holding.** A program cell's tick carries the time it was
+  consulted (`title="consulted at 14:32:05"`, absolute — a relative time baked into an
+  attribute is wrong the moment it is written), and flips to **edited since consulted** as soon
+  as the textarea diverges from what was actually loaded. That state, not the clock, is the
+  reader's real question, and it became easy to get wrong the moment Run started consulting
+  cells by itself.
+- **Reset, at two scales.** Per cell: restore the chapter's text *and re-consult it*, because
+  putting the page back without putting the engine back leaves them disagreeing. Page-level:
+  **restart engine**, which throws the worker away and replays the consult log — the documented
+  answer for a `:- dynamic` cell whose state lives in no file. Verified in a browser: a counter
+  mutated to 41 is 0 again afterwards. Per-cell *unconsult* is deliberately absent; it raises
+  "what happens to the cells that depended on it", and page-level restart has no such question.
+- **The engine's state is visible**: *engine not started* until something needs it, which is
+  also the plainest evidence that a cold chapter is readable without it.
+- **The chapter is readable before the engine arrives, and without it.** A query cell renders
+  the answers stored in the file — labelled as the chapter's, not the reader's (docs/modes.md
+  §3) — and the 5.9 MB WASM bundle is fetched only when someone presses Run. Verified in a
+  browser by watching the network: on a cold load there is no request for it at all. This is
+  what makes a published chapter degrade to a book rather than to a blank page.
+- **Saved answers that no longer follow from the program above them are marked**, before first
+  paint and with no engine: the stored `input-hash` is compared against a 64-bit FNV-1a of the
+  goal and the program cells preceding it. Marked rather than hidden — never silently
+  discarded and never silently trusted.
+- **A chapter is a file.** `prolog-notebook/page` fetches a `.prolog.md`, parses it, renders
+  the whole page and wires up the cells: `await load('chapter-04-cut.prolog.md')`. Program and
+  query cells are generated from the model rather than marked up by hand, which is what makes
+  writing a chapter *writing markdown*.
+- **The `once/1` chapter is now that file**, and the hand-written page it was ported from is
+  deleted. Same prose, same four queries, same answers — six duplicated sons, one from `son_a`,
+  three from `son_b`, `true` for the ground goal — driven from
+  [`notebooks/ch04-cut.prolog.md`](notebooks/ch04-cut.prolog.md) instead of 200 lines of HTML.
+  It carries its saved answers and their `input-hash`es, and a test asserts the chapter agrees
+  with them, so an edit to a program cell that invalidates an answer below it fails CI.
+  On the repo page it reads as a document: prose as prose, Prolog syntax-highlighted, and the
+  prediction still hidden behind a `<details>` you have to click.
+- **Run brings its own context.** Pressing Run on a query consults the program cells above it
+  first, so a reader who lands halfway down a chapter gets an answer rather than
+  `Unknown procedure`. Cells already loaded at their current text are skipped, so the second
+  Run of a chapter consults nothing and an edited cell invalidates only itself.
+  There is no dependency graph, and there is no need for one: **Prolog has no load-time name
+  binding** — `q(X) :- p(X)` merely mentions `p/1`, which is looked up when it is *called* — so
+  consult order cannot affect correctness, and at ~3.5 ms a cell there is nothing to gain by
+  computing one.
+- **An error a reader can act on.** `wasm:wasm_call_string/3: Unknown procedure: son_a/1` is
+  our own plumbing in the middle of a lesson; it now reads `Unknown procedure: son_a/1`, and
+  where the predicate is defined by a cell *below* the query, the notebook says so and names
+  it. Context frames belonging to the reader's own code are untouched — `//2: Arithmetic:
+  evaluation error` still names the division that failed.
+- `prolog-notebook/render` — the cell model to HTML **strings**, DOM-free. The same emitter
+  serves the browser today, the static build in v0.3 and the VS Code renderer later; one
+  implementation, four consumers.
+- A generated program cell carries its notebook id as `data-cell`, and the consult is named by
+  it. SWI now says `Previously defined at /p-family.pl:20` — a warning that names a cell the
+  reader can find in the source, rather than `/cell-3.pl`.
+- **`notebooks/` holds chapters and `viewer/` holds the one page that renders them.** They had
+  both been living in `example/`, under a script (`npm run example`, now `npm run dev`) that
+  actually served the repo root. A chapter is not an example, there will be many of them, and
+  the first one had been doubling as a parser fixture *with a deliberately wrong `input-hash`* —
+  which a file anybody is meant to read must never carry. The wrong hash now lives in
+  `test/fixtures/stale-output.prolog.md`, where being wrong is the point.
+- **The engine runs in a Web Worker** in the browser, so a runaway goal costs a click on
+  Stop rather than the tab. Verified by driving Chrome: with `loop` spinning, timers still
+  fire, layout still runs, and the notebook is usable again afterwards.
+- `session.abort()` and `session.restart()` — terminate the worker and replay the consults
+  into a new engine. Affordable only because one cell is one virtual file, so a chapter's
+  clause store rebuilds in milliseconds; terminating also reclaims the whole WASM heap, so a
+  memory blow-up and an infinite loop have the same cure.
+- A `stop` button in the query cell, and a `ConsultLog` holding one entry per cell — the
+  latest text, not a history — so a replay restores what the reader actually has.
+- `prolog-notebook/format` (0.1.3, listed here for completeness): the notebook parser,
+  canonical serialiser and `input-hash`.
+
+### Fixed
+
+- **The browser session had no `restart()`**, while the in-process one and the README both did
+  — found by wiring a button to it. Both sessions now implement one interface, and a test
+  compares them, because nothing else could: Node never runs the worker session and a browser
+  never runs the other.
+- `session.formatSolution()` is **removed** rather than added to the worker session. The
+  engine-backed one renders through SWI; a worker-backed one could only fall back to the
+  engine-free spelling, so the same call would have quietly meant two different things
+  depending on where it ran. Use `query.next().text`, or the exported `formatSolution()`.
+
+### Changed
+
+- `createSession()` returns a session whose methods are all async. Migration is mechanical:
+  `session.consult(…)` → `await session.consult(…)`, `q.next()` → `await q.next()`.
+- The browser page no longer loads the WASM bundle with a `<script>` tag; the worker loads
+  it. A page may pass `swiplUrl` if it lives somewhere unusual.
+- Node still runs the engine in-process and is **not** protected against a runaway goal. The
+  CLI is not an interactive page; the limitation is documented rather than implied.
+
+### Notes
+
+`assert`/`retract` state does not survive an abort, which is already the documented
+behaviour of "restart engine and run all" (`docs/format.md` §8) rather than a new surprise.
+
 ## [0.1.2] — 2026-08-04
 
 Two bugs, both of which made the library quietly say something untrue. Found by

package/README.md

@@ -32,7 +32,7 @@ the reader clicks a link.
 The reason this is not "Jupyter with a different kernel" is the button marked `; next`.
 
 Jupyter's model is request/response: run a cell, get a result. Prolog's model is a stream of
-solutions you walk through. In the included example, `is_son(X)` reports edward *twice* — and
+solutions you walk through. In the included chapter, `is_son(X)` reports edward *twice* — and
 that duplication **is the lesson**, because it means Prolog found two proofs. A notebook that
 showed only a final list of results would have hidden the very thing worth teaching.
 
@@ -44,15 +44,63 @@ So a query cell gives you the first solution, and then you step.
 git clone https://github.com/jarecsni/prolog-notebook
 cd prolog-notebook
 npm install
-npm run example        # then open http://localhost:8777/example/
+npm run dev            # serves the repo root on :8777
 ```
 
-The example is a real worked section — the `once/1` placement puzzle — not a widget demo.
-Predict what each version returns before you press Run.
+Then open **http://localhost:8777/viewer/**. That is a chapter — the `once/1` placement puzzle,
+a real worked section rather than a widget demo — rendered from
+[`notebooks/ch04-cut.prolog.md`](notebooks/ch04-cut.prolog.md). Predict what each version
+returns before you press Run.
 
-It has to be **served over HTTP**. Opening `example/index.html` straight from disk leaves the
-buttons inert, because browsers block ES modules over `file://` — the page detects this and
-says so rather than failing silently.
+Edit that file, reload, and the chapter changes: prose, Prolog, margin note and prediction box
+are all in it, and there is no HTML anywhere. Point the viewer at any other notebook with
+`?src=`.
+
+| | |
+|---|---|
+| `notebooks/` | chapters. The product. |
+| `viewer/` | one shell page that renders any of them. Replaced by `build` in v0.3. |
+
+The chapter also reads on the repo page, [as a file](notebooks/ch04-cut.prolog.md), with no
+build step and no site: prose as prose, Prolog syntax-highlighted, the saved answers in place,
+and the prediction still hidden behind a `<details>` you have to click. That is the whole
+reason the format is markdown.
+
+It has to be **served over HTTP**. Opening the page straight from disk leaves the buttons
+inert, because browsers block ES modules over `file://` — the page detects this and says so
+rather than failing silently.
+
+## Fill in a chapter's answers
+
+A chapter's saved answers have to come from a real run — a hand-written output block is the
+author's *guess* at what SWI prints, published as though it ran. So write the file with no
+output blocks and let the engine fill them in:
+
+```sh
+npx prolog-notebook run notebooks/ch04-cut.prolog.md
+```
+
+It consults every program cell, runs every query below it, and writes the solution sequences
+back into the file along with an `input-hash` for each — which is what makes the chapter render
+complete, and render as *current*, before the engine arrives. Running it again on an unchanged
+chapter changes nothing.
+
+| flag | |
+|---|---|
+| `--limit <n>` | solutions to take from one query before stopping. Default 100. |
+| `--stdout` | print the result instead of writing the file |
+| `--quiet` | report only failures |
+| `--version` | the tool's version, **the SWI-Prolog version it will run your chapters with**, and the copyright |
+
+Two things it will not do. A query stopped at the limit is written **without** a terminator,
+which is the format's way of saying the search was never exhausted — `false.` there would be a
+forgery. And if a program cell fails to load, nothing is written at all: every answer below it
+was produced against a chapter that does not exist.
+
+It has no defence against a non-terminating goal yet — the engine runs in this process, so
+`loop :- loop.` hangs the command. Say the word `--limit` all you like; a runaway *consult* is
+not a solution count. Fixing it properly means a worker thread, and it is the prerequisite for
+putting this in CI.
 
 ## Use it
 
@@ -62,36 +110,70 @@ Headless, in Node — this is how you test that every example in a document stil
 import { createSession, formatSolution } from 'prolog-notebook';
 
 const session = await createSession();
-session.consult(`
+await session.consult(`
   male(edward).  male(alfred).
   father(albert, edward).  mother(victoria, edward).
   parent(X, Y) :- father(X, Y) ; mother(X, Y).
   is_son(X) :- male(X), parent(_, X).
-`);
+`, 'cell-family');
 
 // Step solutions one at a time, as at the prompt
 const q = session.query('is_son(X)');
 let r;
-while (!(r = q.next()).done) console.log(formatSolution(r.solution));
+while (!(r = await q.next()).done) console.log(r.text);
 
 // …or drain it
-const { solutions } = session.query('is_son(X)').all();
+const { solutions } = await session.query('is_son(X)').all();
 ```
 
-In a browser, load the WASM bundle with a `<script>` tag, then import from
-`prolog-notebook/browser`. See [`example/index.html`](example/index.html) for the cell
-markup and [`src/notebook.js`](src/notebook.js) for the wiring.
+**Every call is awaited**, because in the browser the engine runs in a Web Worker. A Prolog
+query is synchronous WASM, so a goal that never terminates blocks whatever thread it is on —
+and non-termination is *chapter material* in a Prolog book. Running the engine somewhere that
+can be terminated is what turns `loop :- loop.` from a dead tab into a Stop button.
+
+In a browser, import from `prolog-notebook/browser` and let it start the worker; the page does
+**not** need a `<script>` tag for the WASM bundle any more, because the worker loads it. See
+[`viewer/index.html`](viewer/index.html) for the whole of a host page, and
+[`src/notebook.js`](src/notebook.js) for the wiring.
+
+```js
+import { createSession } from 'prolog-notebook/browser';
+const session = await createSession();       // boots the worker
+await session.abort();                       // stop a runaway goal; cells are re-consulted
+```
+
+To render a notebook file instead of marking up cells by hand — the whole page from one call:
+
+```js
+import { load } from 'prolog-notebook/page';
+await load('chapter-04-cut.prolog.md');      // parse, render into <main>, wire up the cells
+```
+
+`prolog-notebook/format` (parse, serialise, `inputHash`) and `prolog-notebook/render` (model to
+HTML strings) are exported separately, and neither touches the DOM — the same two modules back
+the browser, the CLI runner and a future VS Code serializer.
+
+Node runs the engine in-process and is deliberately **not** protected: a non-terminating goal
+will hang it. The CLI is not an interactive page, and pretending otherwise would hide the
+difference.
 
 ### API
 
 | | |
 |---|---|
-| `createSession(options?)` | boots SWI-Prolog; returns a `PrologSession` |
-| `session.consult(text, name?)` | loads a clause base into `user`; `{ok, error?}` |
-| `session.query(goal)` | opens a query; returns a `PrologQuery` |
-| `query.next()` | one solution: `{done, solution?, error?}` |
-| `query.all(limit?)` | drains it: `{solutions, error?, truncated}` |
-| `formatSolution(s)` | renders bindings the way a top level would |
+| `createSession(options?)` | boots SWI-Prolog; returns a session |
+| `await session.consult(text, name?)` | loads a clause base into `user`; `{ok, error?, messages}` |
+| `session.query(goal)` | opens a query; nothing runs until you pull a solution |
+| `await query.next()` | one solution: `{done, solution?, text?, error?}` |
+| `await query.all(limit?)` | drains it: `{solutions, error?, truncated}` |
+| `await session.abort()` | terminates a running goal and replays the consults |
+| `await session.restart()` | same, without anything needing to be running |
+| `formatSolution(s)` | renders bindings the way a top level would, with no engine |
+
+Abort is cheap because of a decision made elsewhere: one cell is one virtual file, so the
+clause store rebuilds from the cells in milliseconds. Terminating the worker also reclaims the
+whole WASM heap, so a runaway loop and a memory blow-up have the same cure. Assert/retract
+state does not survive it — see [`docs/format.md`](docs/format.md) §8.
 
 ## Two things that will bite you if you build this yourself
 
@@ -99,7 +181,19 @@ Both were found by driving a real browser, not by reading documentation.
 
 **Module context.** `prolog.query(Goal)` runs with `system` as its context module, while
 `consult/1` loads into `user`. Unqualified goals raise `Unknown procedure: system:foo/1`
-*even though the consult reported success*. Goals are wrapped as `user:( Goal )`.
+*even though the consult reported success*. Goals are read and called in `user`.
+
+**One round trip per answer, or the variables come apart.** Formatting each binding with its
+own `term_string/2` call loses the fact that two of them are the *same* variable:
+`app([1,2], Tail, L)` came out as `L = [1,2|_20306],  Tail = _20428` where a real toplevel
+prints `L = [1, 2|Tail]`. Render the whole answer inside Prolog, in one call, with the goal's
+own `variable_names`.
+
+**The engine version is not the package version, and it must not float.**
+`swipl-wasm@8.0.4` ships SWI-Prolog 10.1.10; `8.0.7` ships 10.1.13. Two installs of the same
+release, ten minutes apart, ran different Prologs. Since a notebook's saved answers are only
+true of the engine that produced them — and SWI's answer spelling changes between releases —
+the dependency is pinned exactly, and moving it is a commit with the chapters re-run in it.
 
 **The last solution arrives with `done`.** `next()` can return `{done: true, value: {...}}` —
 a final binding and the end of the search in a single step. Treating `done` as "stop, no more
@@ -110,18 +204,27 @@ lesson about backtracking quietly teaches the wrong thing.
 
 Working and tested:
 
-- execution core, environment-agnostic (`src/engine.js`), 8 passing tests
+- execution core, environment-agnostic (`src/engine.js`), run in a Web Worker in the browser
 - Node entry point, browser entry point
-- program cells and query cells with `Run` / `; next` / `all`
-- the worked example
+- **a chapter is a file** — parse, render and mount a `.prolog.md`, cells and all
+- **a chapter is readable cold** — saved answers render with no engine, and are marked stale
+  when the program above them has moved
+- program cells and query cells with `Run` / `; next` / `all` / `stop`, per-cell reset, and a
+  page that says what the engine is holding
+- `hold` and `rerun="auto"` — the author decides what a reader may see and when it refreshes
+- **the CLI runner**: `prolog-notebook run` executes a chapter headlessly and writes its
+  answers back
+- download your own copy of a chapter, answers and all
+- 186 passing tests
 
 Not built yet:
 
-- **a file-backed renderer** — reading `.ipynb` or markdown and *generating* the cells.
-  Today the example's cells are hand-written HTML. This is the next real piece of work.
+- `--check` — run a chapter in CI and fail the build when its answers have drifted. Needs a
+  timeout first: a test suite that can hang forever is not a test suite.
+- `build` — a static page a reader can open, without a dev server
 - custom elements (`<prolog-program>`, `<prolog-query>`) so notebooks drop into any static site
 - a VS Code notebook controller — VS Code supplies the UI, this supplies the kernel, still no Python
-- a CLI runner, to execute a document's cells in CI and fail the build when an example rots
+- persistence, so a reader's edits survive a reload
 - `trace/0` integration, for visible backtracking — where [prolog-trace-viz][ptv] would plug in
 - syntax highlighting
 

package/bin/prolog-notebook.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// The command line. Thin on purpose: argument parsing, files, and words for a
+// terminal. Everything it does lives in src/run.js and src/export.js, so a VS
+// Code "run all" and a future --check get the same behaviour without going
+// through a shell (869ectt38, 869ectt3e).
+import { createRequire } from 'node:module';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { parse, NotebookError } from '../src/format.js';
+import { prologVersion } from '../src/engine.js';
+import { buildLine, currentBuild } from '../src/build-info.js';
+import { banner } from '../src/version.js';
+import { exportSource } from '../src/export.js';
+import { runNotebook, DEFAULT_LIMIT } from '../src/run.js';
+
+// The engine is imported WHERE IT IS USED, never at the top. src/node.js pulls in
+// 5.9 MB of WebAssembly at module scope, so a static import here would mean that
+// `--help` on a broken install fails before it can print anything — and the two
+// commands most likely to be typed at a broken install are --help and --version.
+const engine = () => import('../src/node.js');
+
+// `prolog-notebook run --stdout file | head` closes the pipe while we are still
+// writing to it. That is the reader using the shell correctly, not an error, and
+// a command that answers it with an unhandled EPIPE and a stack trace is
+// complaining about being used properly.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (e) => {
+    if (e.code !== 'EPIPE') throw e;
+  });
+}
+
+// Only for swipl-wasm's own version: everything about THIS package is in
+// src/version.js, where a page can import it too.
+const require = createRequire(import.meta.url);
+
+const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
+
+  prolog-notebook run <file.prolog.md>...   run every cell, write the answers back
+
+Options
+  --limit <n>   solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
+  --stdout      print the result instead of writing the file
+  --quiet       report only failures
+  --version     version, engine and copyright
+  -h, --help    this
+
+A query that stops at the limit is written without a terminator, which is the
+format's way of saying the search was never exhausted. Nothing is invented.
+`;
+
+/**
+ * A runaway goal hangs this process — the engine is in-process here, so there is
+ * no thread left to notice (869ejgyax). Stated rather than implied, because the
+ * moment this runs a file someone else wrote it stops being an annoyance.
+ */
+const RUNAWAY_WARNING = 'note: a non-terminating goal will hang this command; it has no timeout yet (869ejgyax)';
+
+/**
+ * Who this is, and — the part that is not on anyone's disk — which Prolog it
+ * will run your chapters with.
+ *
+ * THE ENGINE LINE EARNS ITS 59 MILLISECONDS. swipl-wasm's own version says
+ * nothing about SWI's: 8.0.4 ships 10.1.10. A notebook's saved answers are only
+ * true of the engine that produced them, so this is the one fact here that a
+ * reader could not have looked up.
+ *
+ * An engine that will not load is REPORTED, not fatal. "I cannot start Prolog"
+ * is exactly what someone running --version to diagnose a broken install needs
+ * to be told, and exiting non-zero would hide it behind a shell error.
+ */
+async function version() {
+  // The same line the page shows in its panel: src/version.js, imported by both.
+  const lines = [banner()];
+  try {
+    const { createSession } = await engine();
+    const swipl = await prologVersion(await createSession());
+    const wasm = `swipl-wasm ${require('swipl-wasm/package.json').version}`;
+    lines.push(swipl ? `Powered by SWI-Prolog ${swipl}, ${wasm}` : `Powered by ${wasm}`);
+  } catch (e) {
+    // Not "powered by" anything, so it does not say so. Someone running this to
+    // find out why nothing works needs the reason, not a formula.
+    lines.push(`SWI-Prolog could not be started: ${e.message}`);
+  }
+  // Omitted rather than guessed at when there is neither a baked file nor a git
+  // repository — a line that says "unknown" three times is worse than no line.
+  lines.push(buildLine(currentBuild()));
+  // The blank line is deliberate: this is a banner, and a banner that runs into
+  // the next shell prompt reads as an error message.
+  return `${lines.join('\n')}\n\n`;
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (!args.length || args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.includes('--version') || args.includes('-V')) {
+    process.stdout.write(await version());
+    return 0;
+  }
+
+  const command = args.shift();
+  if (command !== 'run') {
+    process.stderr.write(`unknown command "${command}"\n\n${USAGE}`);
+    return 2;
+  }
+
+  const options = { limit: DEFAULT_LIMIT, stdout: false, quiet: false };
+  const files = [];
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--limit') {
+      const value = Number(args.shift());
+      if (!Number.isInteger(value) || value < 1) {
+        process.stderr.write('--limit takes a positive whole number\n');
+        return 2;
+      }
+      options.limit = value;
+    } else if (arg === '--stdout') options.stdout = true;
+    else if (arg === '--quiet') options.quiet = true;
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`unknown option "${arg}"\n\n${USAGE}`);
+      return 2;
+    } else files.push(arg);
+  }
+
+  if (!files.length) {
+    process.stderr.write('run needs at least one file\n');
+    return 2;
+  }
+  if (!options.quiet) process.stderr.write(`${RUNAWAY_WARNING}\n`);
+
+  // One engine for the whole invocation, restarted between files. A notebook is
+  // a world of its own — one cell is one virtual file, and two chapters may
+  // define the same predicate — so carrying clauses across would let a file pass
+  // because of what the file before it happened to load.
+  const { createSession } = await engine();
+  const session = await createSession();
+  let status = 0;
+
+  for (const file of files) {
+    await session.restart();
+    status = Math.max(status, await runFile(file, session, options));
+  }
+  return status;
+}
+
+async function runFile(file, session, options) {
+  const name = basename(file);
+  let notebook;
+  let source;
+  try {
+    source = readFileSync(file, 'utf8');
+    notebook = parse(source);
+  } catch (e) {
+    // The parser's line numbers are the file's own, so its message is already
+    // the most useful thing anyone could say here.
+    process.stderr.write(`${file}: ${e instanceof NotebookError ? e.message : e.message}\n`);
+    return 1;
+  }
+
+  const { edits, failures, warnings } = await runNotebook(notebook, session, {
+    limit: options.limit,
+    onCell: (event) => {
+      if (options.quiet) return;
+      if (event.kind === 'program') {
+        process.stderr.write(`  ${event.ok ? '✓' : '✗'} ${event.id}\n`);
+        return;
+      }
+      const answers = event.error
+        ? `error: ${event.error}`
+        : `${event.solutions.length} solution${event.solutions.length === 1 ? '' : 's'}`
+          + (event.truncated ? ` (stopped at ${options.limit}, not exhausted)` : '');
+      process.stderr.write(`  ${event.error ? '✗' : '✓'} ${event.id} — ${answers}\n`);
+    },
+  });
+
+  for (const warning of warnings) process.stderr.write(`  ! ${warning.id}: ${warning.text}\n`);
+
+  if (failures.length) {
+    // NOTHING IS WRITTEN when a program cell failed to load. Every answer below
+    // it was produced against a chapter that does not exist, and writing those
+    // into the file would publish them as though they did.
+    for (const failure of failures) {
+      process.stderr.write(`${file}: cell ${failure.id} did not load: ${failure.error}\n`);
+    }
+    process.stderr.write(`${name}: not written\n`);
+    return 1;
+  }
+
+  const text = exportSource(notebook, edits);
+  if (options.stdout) {
+    process.stdout.write(text);
+    return 0;
+  }
+  if (text === source) {
+    if (!options.quiet) process.stderr.write(`${name}: unchanged\n`);
+    return 0;
+  }
+  writeFileSync(file, text);
+  if (!options.quiet) process.stderr.write(`${name}: written\n`);
+  return 0;
+}
+
+process.exitCode = await main(process.argv);