docs: check C ABI, generator protocol, conformance, inspect and doc against the code

docs/docs/reference/c-abi.md

@@ -14,7 +14,7 @@ transports, async and dispatch stay in each host.
   comments are the doc comments of the Rust source.
 - **Why it exists and what was decided:** [one protocol core](../proposals/shared-runtime-core/core-interface.md).
 
-This page was written against runtime `main` at `cb41d31`. Where it and the
+This page was checked against runtime `main` at `b101fe9`. Where it and the
 header disagree, the header is right.
 
 ## Version
@@ -382,9 +382,9 @@ cbindgen --config cbindgen.toml --output include/comline.h
   (`tests/c/vectors.c`, C11 against `comline.h`) and Node (`js/test/vectors.test.mjs`,
   against the wasm32 build). C runs against the static library, the dynamic
   library, and the static library under ASan and UBSan.
-  - The cases are every one in `name-hash` (8), `handshake` (9), `envelope`
+  - The cases are every one in `name-hash` (8), `handshake` (13), `envelope`
     (8), `framing-datagram` (9), `framing-datagram2` (12) and `framing-jsonrpc`
-    (19): 65 in all. Each harness fails on any mismatch, and on a case count
+    (26): 76 in all. Each harness fails on any mismatch, and on a case count
     that differs from the vectors'.
   - The nine `datagram@1` cases have no connection form. For them the harness
     checks that the ABI refuses `datagram@1`.
@@ -443,7 +443,10 @@ rustc 1.98.0. Message mode, a 16-byte payload:
   16 B.
 - **`jsonrpc@1` decoding is its own cost.** It scans the frame with serde_json
   at about 2.8 instructions a byte (185,825 for 64 KiB, on the core). The
-  crossing adds the same 153 on top.
+  crossing adds the same 153 on top. Since these figures,
+  [runtime#76](https://github.com/ComlineProject/runtime/pull/76) made the
+  decoder check the `jsonrpc` version and the shape of `params`, which raised
+  the core side of the `jsonrpc@1` `feed`; the crossing is unchanged.
 - **runtime#60 cut it.** The overlap check was most of `encode_request`'s
   crossing. From the PR's body, measured locally at the same paths:
   `encode_request` `datagram@2` 965 to 742, `feed` `datagram@2` 319–327 to

docs/docs/reference/conformance.md

@@ -68,7 +68,7 @@ A case is one operation and the bytes it must produce:
 | `input` | the operation's input |
 | `bytes` | the encoded form, lowercase hex |
 | `expect` | optional: `"reject"` means decoding `bytes` must fail; the input then names only what selects the decoder (the framing) |
-| `compare` | optional: `"json"` compares JSON text as JSON (RFC 8259) instead of byte for byte |
+| `compare` | optional: `"json"` compares JSON text as JSON (RFC 8259) instead of byte for byte; see [Comparing as JSON](#comparing-as-json) |
 
 - **Bytes** are lowercase hex.
 - **64-bit and wider integers** (`ir_hash`, `request_id`, `u64`, `i64`, `u128`,
@@ -95,6 +95,20 @@ A case is one operation and the bytes it must produce:
 A framing is proven with `request` and `response` cases; a format with `encode`
 and `decode` cases.
 
+### Comparing as JSON
+
+A case with `"compare": "json"` holds bytes that are JSON text (a JSON value,
+or a JSON-RPC frame). An encode passes when its output equals `bytes` as JSON:
+
+- Whitespace and member order don't matter.
+- **Numbers compare as exact decimals:** `1` equals `1.0`, but
+  `9007199254740992` doesn't equal `9007199254740993`, though both read as the
+  same double ([runtime#72](https://github.com/ComlineProject/runtime/pull/72)).
+- Strings compare by the text they hold, however they're escaped:
+  `"app.Chat\/count"` equals `"app.Chat/count"`.
+- The same holds for JSON inside a frame: JSON-RPC params, results and error
+  data.
+
 Values and types are written in a typed encoding (`{"u8": 255}`,
 `{"struct": {"name": "Point", "fields": [...]}}`, and so on). The full list is
 in the
@@ -206,8 +220,9 @@ comline conformance --impl "<command line>" [--encoding <name>]... [--corpus <di
 
 The flags are described in the
 [CLI reference](cli.md#commands). The implementation runs under the same rules
-as an external generator: a cleared environment, a time limit (60 seconds by
-default) and a capped stdout, with its stderr shown. The command line is split
+as an external generator: a cleared environment, a time limit (`--timeout`,
+60 seconds by default, for every case together) and a capped stdout, with its
+stderr shown. The command line is split
 on whitespace, with no shell quoting, and a bare program name is looked up on
 `PATH`.
 

docs/docs/reference/generator-protocol.md

@@ -84,7 +84,7 @@ to a program whose `Description` lists the renderer at the model version. A
 
 | Field | Type | Meaning |
 |---|---|---|
-| `renderer` | string | the renderer's id, from `Description.renderers`: `markdown` |
+| `renderer` | string | the renderer's id, from `Description.renderers`: `markdown` or `html` for the official ones |
 | `model_version` | integer | the documentation model's version (`DOC_MODEL_VERSION`, `1`), readable without parsing `model` |
 | `model` | string | the documentation model as JSON text, in the shape of [`doc-model/1.json`](../schemas/doc-model/1.json) |
 | `options` | `{ links, version, versions, notes }` | see below |
@@ -94,7 +94,7 @@ to a program whose `Description` lists the renderer at the model version. A
 | `links` | a dependency's name (or `std`) to the base URL of its docs |
 | `version` | set when this render is one version of a multi-version site: the version's folder (`0.2.0`, `0.3.0-dev.2`, `unreleased`). The files land in `<site>/<version>/`, so the site's shared files are at `../`. Absent for a site of its own. |
 | `versions` | set for a site's index render: every version, oldest first, each `{ id, release, kind, model }`. `release` is the release a dev build leads to (`0.3.0` for `0.3.0-dev.2`), itself for a release, `unreleased` for the working tree; `kind` is `release`, `dev` or `unreleased`; `model` is that version's model as JSON, with its `changelog` from the version before it in the list. The files land at the site's root, and the request's own `model` is the newest version's. |
-| `notes` | plain-text notes for every page of this version: what an old version's documentation lacks |
+| `notes` | plain-text notes for every page of this version: what a built version's documentation lacks (headers, for one built before they were stored; wire summaries, which no built version records yet) |
 
 A renderer accepts every option and ignores the ones it has no use for. The
 answer is `Render(Generated)`: files, checked like a generator's.
@@ -155,7 +155,8 @@ target's version.
 
 - **Describe:** the CLI's protocol version must be inside `protocols`, and its
   IR format must be in `ir_formats`. Otherwise it refuses the generator and names
-  both sides.
+  both sides. The other way round, `serve_stdio` answers a request whose
+  `protocol` or `ir_format` isn't its own with an `Error` naming both.
 - **Language:** the generator must offer the target's language at the target's
   version, or the CLI refuses it.
 - **Renderer:** for `comline doc`, the program must list the format in
@@ -201,5 +202,6 @@ The `comline_codegen::protocol` module exports:
   `handle`, which does the same on bytes;
 - `serve_stdio(registry)`: a generator process's whole `main`. A registry
   holds renderers too (`Registry::register_renderer`), so one binary can
-  generate, render, or both. The official Markdown renderer is
-  `comline-doc-markdown` in the generation repository.
+  generate, render, or both. The official renderers are
+  `comline-doc-markdown` and `comline-doc-html` in the generation repository;
+  both are linked into `comline` and both set `sites`.

docs/docs/reference/tools/doc.md

@@ -15,9 +15,9 @@ walkthrough, see [Documenting your schemas](../../guide/documenting.md).
 | Flag | Default | Meaning |
 |---|---|---|
 | `--out <dir>` | `[doc] out`, else `docs/api` | Where to write, relative to the project. |
-| `--version <v>` | every version | Document only this built version, into `<out>/<format>/<v>/`: a version string, a commit hash (4+ characters), or `HEAD`. |
+| `--version <v>` | every version | Document only this built version, into its version's folder, `<out>/<format>/<version>/`: `<v>` is a version string, a commit hash (4+ characters), or `HEAD`. |
 | `--changelog-from <v>` | `[doc] changelog_from` | With `--version`: add what changed from built version `<v>` to the documented one. |
-| `--format <f>` | `[doc] formats`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. Repeat it, or separate formats with commas. |
+| `--format <f>` | `[doc] formats`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. Repeat it, or separate formats with commas. With `[doc] renderer` set, every format but `json` comes from that renderer ([External renderers](#external-renderers)). |
 | `--open` | off | After rendering, open the first format's index, as `comline doc open` does. With `--version`, it opens that version's own `index.html` or `index.md` (`model.json` for `json`). |
 
 ## Opening the result
@@ -27,8 +27,8 @@ system's default handler: `<out>/<format>/index.html`, `index.md` or
 `index.json`, for `html`, `markdown` or `json`. `--out` is read as `comline doc`
 reads it.
 
-- With no `<format>`, it opens `html` if that is among `[doc] formats`, else
-  the first configured format.
+- With no `<format>`, it opens `html` if that is among `[doc] formats` or
+  `<out>/html/index.html` is already there, else the first configured format.
 - If the file isn't there, it renders that format first, exactly as
   `comline doc --format <format>` would. If it is, it opens it as it is,
   without re-rendering, and says so in one line with how to refresh it
@@ -71,7 +71,8 @@ docs/api/
 ```
 
 - A dev build's folder is its full version (`0.2.0-dev.1`), and it belongs to
-  the release it leads to (`0.2.0`).
+  the release it leads to (`0.2.0`). A version built more than once keeps its
+  newest build.
 - The working tree appears as `unreleased` only when its schemas or headers
   differ from the last build. With nothing built, it is the only version.
 - Each version carries the changelog from the version before it in the list
@@ -112,7 +113,7 @@ version's folder:
 | `<module>.md` | Per schema (`types::user` → `types/user.md`): its `//!` header, a table of its declarations (Item, Summary, then Type and Value, each only when some declaration in the module has one: a constant's type and value, a type alias's target), then each one with its `///` docs, annotations, fields and arguments (a field's own docs, else its parent's `/// @name:` line), enum variants, an error's ordinal and message, a validator's targets, parameters and asserts, and each protocol's functions and wire summary. |
 | `changelog.md` | With a changelog: breaking changes, additions and other changes. Each entry is a heading line (its severity, `MAJOR`, `MINOR` or `PATCH`, and a title such as `` `Orders.place`: signature changed `` linking to the declaration), then the change as a fenced `diff` block: the old IDL line with `-`, the new with `+`. An addition has only the `+` line, a removal only the `-` line, and a change with no IDL to show (a docstring, an error's ordinal, guarantees) a sentence instead. A release shows its changes since the previous release; a dev build its step, then a link to its changes since the last release, listed below it. |
 | `deps/<package>/<module>.md` | Per module of a dependency without a published base URL: what the package reaches of it, as `<module>.md`. |
-| `nav.yml` | A `nav` list for mkdocs or zensical: the package's modules, then a `Dependencies` section (a dependency's pages, or its published base URL). |
+| `nav.yml` | A `nav` list for mkdocs or zensical: the overview (`index.md`), the package's modules, then a `Dependencies` section (a dependency's pages, or its published base URL), then `Changelog` when there is one. |
 
 `<out>/markdown/index.md` lists the versions, newest first, grouped by release.
 There is no version picker: switching versions on a published site is left to
@@ -151,7 +152,8 @@ writes a self-contained static site per version with the same content:
 | `search.js` | The search index (each declaration's name, kind, module and first line of docs), inlined as data, and the search box's script. |
 
 Every page has a header with the package's name (the version is in the
-picker beside it), a search box, a theme toggle and a version picker, and a
+picker beside it), a version picker with a link to `compare.html`, a search
+box and a theme toggle, and a
 sidebar: the package's modules and their declarations, then a Dependencies
 section, collapsed unless the page is a dependency's, with one group per
 dependency. A group links to the dependency's published docs when it has a
@@ -173,9 +175,14 @@ Changelog
 The header and sidebar work like this:
 
 - The theme toggle cycles auto (the OS setting), light and dark. The choice is
-  kept in the browser's `localStorage` where it's allowed, so it carries across
-  pages and versions, and is applied before the page paints. Where storage is
-  blocked it lasts for the page.
+  applied before the page paints, and carries across pages and versions: it is
+  kept in `localStorage` where that's allowed, and also in the tab
+  (`window.name`) and on internal links (`?theme=`), so it follows the reader
+  under `file://`, where some browsers give each file its own storage, and into
+  a page opened in a new tab.
+- A page's title is `<page> - package <name> - Comline` (`Schema types::user`,
+  `Changelog`, `Compare`), or `package <name> - Comline` for the overview. It
+  carries no version.
 
 - The picker is a native drop-down, newest first, with dev builds grouped under
   the release they lead to, and a Go button. Choosing a version with the mouse
@@ -232,18 +239,23 @@ fields. `dependencies` lists what the package reaches of each dependency
 A built version's model comes from its frozen IR and the `//!` headers stored
 with it. A built version keeps no source, so:
 
-- its protocols have no wire summary.
+- its protocols have no wire summary
+  ([core#153](https://github.com/ComlineProject/core/issues/153));
+- a version built before headers were stored
+  ([core#152](https://github.com/ComlineProject/core/pull/152)) has no headers.
 
-A version built before headers were stored has no headers. Each page of such a
-version opens with a note saying what it lacks, in both formats.
+Each page of such a version opens with a note saying what it lacks, in
+`markdown` and `html`.
 
 ## External renderers
 
 `[doc] renderer = "<path>"` runs a renderer outside `comline`. It speaks the
 [generator protocol](../generator-protocol.md#render), and runs like an
 external generator: a `.wasm` under wasmtime with no filesystem, environment or
 network, a native executable with an empty environment, the same time limit
-(`[doc] timeout`, 60 seconds), output caps and path checks. `comline` asks it
+per call (`[doc] timeout`, 60 seconds), output caps and path checks. It takes
+the built-ins' place: every format but `json`, `markdown` and `html` included,
+is asked of it. `comline` asks it
 to describe itself first and refuses it unless it lists the format, at the
 model version this `comline` writes, in its `renderers`. It renders each
 version's folder with one `Render` each. The site's index is asked for only
@@ -254,4 +266,7 @@ folders alone.
 
 `0` on success. `1` when the package doesn't compile, a version doesn't exist,
 or the renderer refuses or fails. `2` when `--version` or `--changelog-from` is
-given and the project was never built.
+given and the project was never built, or when `.comline/` was written in
+another IR format: `comline doc` checks the store's
+[IR format stamp](../../guide/ir/cas.md#the-ir-format-stamp) before reading any
+built version, and `comline build` rebuilds the store in the current format.

docs/docs/reference/tools/inspect.md

@@ -8,6 +8,12 @@ comline inspect [--json]
 [guarantees](../../guide/idl/protocol.md#giving-up-a-guarantee) it keeps. Like
 `comline check`, it compiles the package and writes nothing to `.comline/`.
 
+It reads the latest build's facts from `.comline/`, so it first checks the
+store's [IR format stamp](../../guide/ir/cas.md#the-ir-format-stamp). A store
+written in another IR format is refused, exiting `2`, with a hint to run
+`comline build`, which rebuilds it in the current format. A project never built
+has no store to check, and shows no facts.
+
 ## What it shows
 
 For each protocol, the package's own and then its dependencies':