# Fuzzing

This page explains how Bookclerk fuzzes its untrusted-input boundaries: the
list of boundaries and their oracles, how the fuzz targets run in CI, how
to add one, and what happens when one finds a crash.

The rule that every boundary ships with a target is in
[ADR: Untrusted-input fuzzing](/docs/adr/untrusted-input-fuzzing/index.md). The rest
of CI is in [Continuous integration](/docs/contributing/ci/index.md).

## Rust boundaries

Coverage-guided fuzzing runs on
[ClusterFuzzLite](https://google.github.io/clusterfuzzlite/) over the
`cargo-fuzz` targets in `fuzz/`. Every untrusted-input boundary ships a
target, a seed corpus and a replay test.

This table is the boundary list. A pull request that adds or widens a
boundary extends it.

| Target | Boundary | Crate |
| --- | --- | --- |
| `sql_parse` | SQL-v1 lexer, packer, grammar and TEXT admission | `bookclerk-plugin-abi` |
| `sql_lower` | Adapter lowering of canonical SQL | `bookclerk-db-exec` |
| `mp4_parse` | ISO-BMFF parse and remux of store downloads | `bookclerk-mp4` |
| `granted_http` | The granted reverse channel | `bookclerk-workerd::granted_http` |
| `workerd_control` | Lines on workerd's stdout, shared with plugin isolates, that report the bridge RPC port on Windows (`--control-fd`) | `bookclerk-workerd::control` |
| `egress_policy` | The guest egress allowlist | `bookclerk-plugin-manifest::EgressPolicy` |
| `egress_relay_head` | Request heads workerd sends the launcher's egress relay (plugin code) and response heads from the servers a plugin reached | `bookclerk-workerd::egress_relay` |
| `egress_bridge` | The workerd egress gate (`bridge/egress.js`) every workerd guest's `fetch()` and `connect()` goes through, run in an embedded JavaScript engine against `EgressPolicy` | `bookclerk-workerd` bridge |
| `plugin_manifest` | `plugin.toml` parse, validation, derived egress and consent | `bookclerk-plugin-manifest` |
| `setting_destination` | Operator-entered values of network settings: the one destination each grants | `bookclerk-plugin-manifest::derive_setting_destination` |
| `cron_schedule` | `[triggers] crons` parse and fire-time search | `bookclerk-plugin-manifest::CronSchedule` |
| `abi_decode` | Every generated Cap'n Proto `read_*` codec, the database envelope decoders, and the reply helpers every payload-free guest reply and guest error goes through (`read_empty`, `read_error`) | `bookclerk-plugin-abi` |
| `db_stream` | `executeStreamed` frames an adapter sends, reassembled by the host and the SDKs under the streamed result budget. The TypeScript and Python SDK tests replay the same corpus as shared vectors against their own decoders | `bookclerk-plugin-abi::ExecuteStreamDecoder` |
| `cover_sink_key` | The key a cover fetcher writes each image under, mapped to a URL slot | `bookclerk-plugin-abi::cover_sink_slot` |
| `cover_process` | Cover images from any public website: sniff, decode under limits, resize, re-encode | `bookclerk-cover::process` |
| `cover_token` | Cover tokens in `/api/covers` and `/api/images` paths, and Gravatar hashes in `/api/avatars` paths: which remote URL a route may fetch | `bookclerk-cover::token` |
| `cover_wire` | Cover worker frames: requests the worker reads, replies the host reads | `bookclerk-cover::wire` |
| `tags_read` | Embedded tags of media files on storage: MP4 `ilst` items, chapter tracks and the audio track's sample description, ID3v2 and ID3v1, FLAC metadata blocks, Ogg Opus and Vorbis headers and comments, read by range in the tag worker | `bookclerk-tags::TagReader` |
| `tags_wire` | Tag worker frames: requests the worker reads, replies the host reads | `bookclerk-tags::wire` |
| `model_pack` | Embedding model files in the embedder plugin's data directory: the model description (`model.json`) and the token-row packs | `bookclerk-model-pack::PackManifest::parse`, `Rows::parse` |
| `archive_extract` | Archives people upload (ZIP, tar and gzip tar): entry names, links, sizes and compression ratios, walked by the media worker's extract job | `bookclerk-archive::extract` |
| `archive_report` | The media worker's extract report, read by the host: written paths, sizes and totals | `bookclerk-archive::ExtractReport::validate` |
| `media_keep_codec` | Audio parts the media worker copies into an M4B without re-encoding them (`output.keep_codec_in_m4b`): MP4 sample entries and tables, Ogg and FLAC headers and packets | `bookclerk-media::package_keeping_codec` |
| `media_decode` | Audio the media worker demuxes and decodes before it encodes or repackages it: store downloads, library copies and files on storage, recognised by their bytes, never their names | `bookclerk-media::decode_pcm_bytes` |
| `media_pcm_wire` | PCM worker frames for the desktop window's player: requests the worker reads, and the worker's whole output (byte-range requests, the stream format, samples, the end) the host reads while the worker decodes untrusted audio | `bookclerk-media::pcm_wire` |
| `cache_headers` | `If-None-Match` on image requests, which decides a `304` answer, and an image host's caching headers, which decide whether and how long a fetched image is kept | `bookclerk-cover::http_cache` |
| `abi_roundtrip` | Every generated Cap'n Proto `read_*` / `write_*` codec pair | `bookclerk-plugin-abi` |
| `scan_page` | One page of a storefront's library scan: its size caps, the cursor it hands back, the account it names, the media kinds of its titles and the refreshed credentials it carries | `bookclerk-plugin-abi::validate_scan_page` |
| `quality_offers` | A storefront's `qualityOffers` reply: how many titles it answers, the stream bounds of each offer and the refreshed credentials it carries | `bookclerk-plugin-abi::validate_quality_offers` |
| `plain_fetch` | A storefront's `fetchTitle` reply: the carrier it fetched and the files it lists by role | `bookclerk-plugin-abi::validate_plain_fetch` |
| `metadata_file_record` | A metadata-file dialect's `parse` answer about a sidecar file: the fields it says the file states, their values and size caps, credit roles, dates and chapter order, and the dialect's declared fields | `bookclerk-plugin-abi::validate_metadata_file_record` |
| `notifier_reply` | A notifier's `send` reply (delivered, retried after a capped wait, or failed, with a cut reason) and the address documents a `validateDestination` answer or a patron's form carries | `bookclerk-plugin-abi::notifications` |
| `notify_raise` | A plugin's `NOTIFY.raise`: the `/notify/raise` JSON body and the Cap'n Proto raise, their type id, fields, patron id, link path, group key and alert | `bookclerk-plugin-abi::notifications::check_raise_params` |
| `ai_run_reply` | A model plugin's reply to a run (vector count, length, finite values, revision and fallback indexes, against the run it answers) and its model listing | `bookclerk-plugin-abi::ai::check_run_output`, `check_models` |
| `ai_run` | A plugin's `AI.run`: the `/ai/run` JSON body and the Cap'n Proto run, their model name and the input for one task | `bookclerk-plugin-abi::ai::check_binding_run_params` |
| `notify_address_body` | The `address` object of a patron's `POST /api/me/notifications/destinations` body: a flat object of strings with no key written twice | `bookclerk-plugin-abi::notifications::AddressFields` |
| `notify_cursor` | The `cursor` query parameter of the notification delivery log and a patron's inbox: a token the caller sends back | `bookclerk-library::NotifyCursor::decode` |
| `event_read` | A plugin's request to read past events (`EVENTS.read`): the `/events/read` JSON body, its cursor, the Cap'n Proto request and page codecs, and the consent, page and time bounds | `bookclerk-plugin-abi::validate_event_read_request` |
| `storage_reply` | A storage plugin's replies to intent operations: `moveMany`, `deleteMany`, `headMany`, `translateKeys` and `changes` replies and the hinted `list` page, checked against the request that asked for them | `bookclerk-plugin-abi::validate_move_many_page` and siblings |
| `s3_event` | Messages on an S3 bucket's notification queue, which the `s3` guest turns into change-feed entries: S3 event notifications, SNS envelopes and EventBridge events, the percent-encoded keys of S3 and SNS records, buckets and prefixes | `bookclerk-storage::s3_events` |
| `r2_event` | What the `r2` guest reads from Cloudflare to serve its change feed: Queues HTTP pull replies (the envelope, lease ids and base64 or text bodies) and the R2 event notifications in them, with their accounts, buckets and prefixes | `bookclerk-storage::r2_events` |
| `b2_reply` | What the `b2` guest reads from Backblaze B2: native API replies (authorization, buckets, upload URLs, file versions, file-name and file-version listings, uploaded parts, errors) and download headers, and the percent-encoding of file names | `bookclerk-storage::b2_api` |
| `socket_request` | A plugin's host-brokered socket request (`Sockets.connect`): its URL, headers, subprotocols, heartbeat pairs and attachment, and the `SocketMessage` the host delivers to a socket handler | `bookclerk-plugin-abi::sockets` |
| `origin_request` | What a relay ingress plugin hands the host: the framed `POST /origin/fetch` body on the isolate bridge, request heads (method, target, headers, client address), response heads, and the public origin `Ingress.start` reports | `bookclerk-plugin-abi::origin` |
| `socket_broker` | What the socket broker does with a remote WebSocket server's frames and closes and a plugin's socket requests: heartbeat answers, deliveries, attachments, the per-instance limit and close reporting | `bookclerk-workerd::socket_table` |
| `socket_route` | A workerd plugin's `env.SOCKETS` calls on the granted reverse channel: the `POST /sockets/<op>` JSON body for `connect`, `send`, `close`, `attachment` and `list` | `bookclerk-workerd::granted_sockets` |
| `webhook_route` | A workerd plugin's `env.WEBHOOKS` calls on the granted reverse channel: the `POST /webhooks/<op>` JSON body for `url`, `pull` and `ack` | `bookclerk-workerd::granted_webhooks` |
| `webhook_message` | The Cap'n Proto `Webhooks` messages a native plugin sends the host (pull and ack requests) and the deliveries the host hands out | `bookclerk-plugin-abi::webhooks` |
| `webhook_request` | A request on the public webhook route `POST /hooks/<token>/<name>` from anyone on the Internet: its body, headers and HMAC-SHA256 signature | `bookclerk-workerd::webhook_request` |
| `guest_sql_authz` | Guest SQL authorization, every host-issued policy shape | `bookclerk-plugin-abi::GuestSqlPolicy` |
| `mux_peer` | Peer frames on the multiplexed byte link | `bookclerk-plugin-sdk::mux` |
| `library_resolve` | Store listings resolved into works, expressions and editions | `bookclerk-resolve` |
| `node_frame` | Node-to-node frames on the library socket, including the public origin a branch reports in its heartbeat | `bookclerk-node-proto::Frame`, `BranchOrigin::parse` |
| `node_account_bundle` | Store accounts and their secrets a library sends a joining branch for its person, a branch offers its library (`accounts.add`), and a sign-in a keeping branch pushes there (`accounts.update`) | `bookclerk-node-proto::parse_account_bundle` |
| `destination_filter` | A storage destination's filter: the body of `PUT /api/config/plugin-instances/{id}/filter` and the stored `core.destination` document | `bookclerk-config::parse_destination_filter` |
| `intake_settings` | A drop folder's settings: the body of `PUT /api/config/plugin-instances/{id}/intake` and the stored `core.intake` document | `bookclerk-config::parse_intake_settings` |
| `intake_items` | A drop folder's listing: object keys, sizes and change signatures grouped into items and settled | `bookclerk-intake::ItemGrouper`, `step` |
| `output_copies` | A library's extra copies of every book, the `copies` array of the `core.output` document (`PUT /api/config/domains/core.output` and the stored row) | `bookclerk-config::OutputCopy`, `validate_copies` |
| `destination_id` | A destination id another node sends: an acquire plan's destination and upload records naming the owner's storage plugin instances | `bookclerk-config::DestinationId::new` |
| `cache_settings` | `cache.*` values from the settings API and CLI: the image caches' budget and unviewed age | `bookclerk-config::parse_cache_setting` |
| `relayed_log_line` | A jailed helper's or guest's stderr line, which the host relays into its own log at the level the line names (never above WARN) | `bookclerk-config::parse_relayed_line` |
| `diagnostics_submit_reply` | The diagnostics collector's reply to an uploaded report, whose `report_id` and `access_code` join the install's report history | `bookclerk-config::parse_submit_reply` |
| `diagnostics_lookup_reply` | The diagnostics collector's answers to a report lookup and deletion, which the daemon and CLI show the operator with issue and pull request links | `bookclerk-config::parse_lookup_reply`, `parse_delete_reply` |
| `libro_catalog` | Libro.fm catalog search pages and audiobook details, which the `libro` guest turns into Discover records, purchase links and prices | `bookclerk-plugin-source-libro` |
| `audible_catalog` | Audible public catalog answers (search results, titles looked up by ASIN and a title's similar titles), which the `audible` guest turns into Discover candidates with their genres and host enrichment reads for ASINs | `bookclerk-audible-catalog::parse_catalog_products` |
| `download_resume` | A store CDN's `Content-Range` and status when a guest resumes an interrupted download, which decide whether the body is appended to the bytes already on disk | `bookclerk-plugin-sdk::resume` (`parse_content_range`, `next_step`) |
| `throttle_reason` | A store's refusal text, which the `audible` guest reads from a refused license request to tell throttling (which pauses the whole account) from a plain refusal | `bookclerk-storefront::is_throttle_reason` |
| `graphicaudio_catalog` | GraphicAudio product pages, which the `graphicaudio` guest turns into catalog records (credits, synopsis, ISBN, running time, price) for title dialogs, the listing pool and the demo seed | `bookclerk-plugin-source-graphicaudio::parse_product_detail` |
| `plan_authz` | Scan and acquire requests a Member sends (over HTTP or through their branch), authorized against the store accounts linked to them | `bookclerk-library::control_plane::plan_scan` / `plan_acquire` |
| `clerk_authorization` | A clerk's library card, the `Authorization: Bookclerk-Clerk <token>` header value that signs a request in as a person | `bookclerk-node-proto::parse_clerk_authorization` |
| `clerk_authorize` | A clerk's authorization request, the `/oidc/authorize` query that decides whether the library shows its library card consent page and where it sends the code | `bookclerk-node-proto::parse_clerk_query`, `clerk_request_problem` |
| `clerk_token_request` | A library card's token exchange, the body of `POST /api/clerk/v1/token` and its match against the code the library stored | `bookclerk-node-proto::parse_clerk_token_request`, `clerk_exchange_matches` |
| `clerk_token_answer` | A library's answer to a clerk's token exchange, read on the clerk before it seals the library card and records the library | `bookclerk-node-proto::parse_clerk_token_answer` |
| `copy_range` | The `Range` header of a copy download, `GET /api/copies/v1/{copy_id}/files/{n}`, which decides which bytes of a library's file are sent | `bookclerk-node-proto::parse_copy_range` |
| `upload_part` | The `Content-Range` header of an upload `PUT`, `/api/node/v1/uploads/{upload_id}/files/{n}`, which decides which bytes of a declared file the body is, or that it only asks where the owner is | `bookclerk-node-proto::parse_upload_range` |
| `tunnel_policy` | Paths of requests a relay ingress plugin carries from the public internet on the `tunnel` transport, which reach the router unless refused as operator-only or outside the exposure the operator chose | `bookclerk-node-proto::normalize_tunnel_path`, `tunnel_refusal` |
| `copy_answer` | A library's answer to a copy download, read on the branch or clerk that took the copy: where its head ends, how many bytes follow and where in the file they are written | `bookclerk-node-proto::copy_answer_head_end`, `parse_copy_answer` |
| `clerk_socket_frame` | The clerk socket's frames, `GET /api/clerk/v1/connect`: what a library reads from a clerk, and what a clerk reads back (changed topics, pages of the library's books with the person's marked, and the grant of a copy with its download token) | `bookclerk-node-proto::parse_clerk_frame`, `parse_library_frame` |
| `instance_config` | A plugin instance's settings, table rows included: the `settings` object of `PUT /api/config/plugin-instances/{id}/config` and the row text of `bookclerk plugins config set` | `bookclerk-library::control_plane::PluginInstanceConfigV1::validate`, `parse_setting_text` |
| `job_cap_request` | A branch's job cap for one library, the body of `POST /api/config/join/capacity` | `bookclerk-library::control_plane::parse_job_cap_request` |
| `sharing_request` | A branch's sharing and work settings for one library, the body of `POST /api/config/join/sharing` | `bookclerk-library::control_plane::parse_sharing_request` |
| `branch_request` | An interlibrary request, the body of `POST /api/branch-requests`, and a request that the library download a book it holds, the body of `POST /api/download-requests` | `bookclerk-library::control_plane::parse_branch_request`, `parse_download_request` |
| `members_books_request` | A library operator's "Acquire all of this branch's members' books" choice, the body of `PUT /api/config/branches/members-books` | `bookclerk-library::control_plane::parse_members_books_request` |
| `upload_manifest` | What a patron sends to start and fill an upload: the body of `POST /api/uploads` and the `Upload-Offset` header of each `PATCH /api/uploads/{id}/files/{member_no}` | `bookclerk-library::control_plane::parse_upload_manifest`, `parse_upload_offset` |
| `member_controls_request` | Member controls an Owner or Administrator sets: the bodies of `PUT /api/users/default-controls` and `PUT /api/users/{id}/controls` | `bookclerk-library::control_plane::parse_member_controls`, `parse_user_controls_request` |
| `patron_scope_request` | A patron scope an Owner or Administrator sets: the bodies of `PUT /api/users/default-scope` and `PUT /api/users/{id}/scope` | `bookclerk-library::control_plane::parse_patron_scope`, `parse_user_scope_request` |
| `chapter_request` | An Administrator's chapter list for an edition or the claim to pin, the bodies of `PUT /api/library/editions/{id}/chapters` and `PUT /api/library/editions/{id}/chapters/pin` | `bookclerk-library::parse_chapter_edit_request`, `parse_chapter_pin_request` |
| `work_split_request` | An Administrator's choice of expressions to move out of a wrongly merged work, the body of `POST /api/library/works/{id}/split` | `bookclerk-library::parse_work_split_request` |
| `playback_request` | What a player sends the playback routes: the bodies of `POST /api/playback/sessions`, `.../{id}/sync` and `.../close`, `PUT /api/playback/progress/{edition_id}`, `POST /api/library/editions/{id}/bookmarks` and `PUT /api/playback/bookmarks/{id}`, the `cursor` of `GET /api/playback/progress`, and the path of `GET /api/playback/sessions/{id}/tracks/{n}` | `bookclerk-library::parse_playback_sync_request`, `parse_progress_cursor`, `parse_open_session_request`, `parse_progress_edit_request`, `parse_new_bookmark_request`, `parse_bookmark_edit_request`, `parse_track_path` |
| `player_request` | What a player app sends the `/player` API: the bodies of `POST /player/login`, session syncs, offline sessions, progress changes and bookmarks, card tokens (`Authorization: Bearer` or `?token=`), list and detail queries, author, series and file ids in paths, and the browser sign-in's queries | `bookclerk-player-api::request`, `ids`, `oauth` |
| `player_socket` | Text frames a player app sends on the live socket, `GET /player/socket.io/` (Engine.IO 4 and Socket.IO 5 over a websocket) | `bookclerk-player-api::socket::parse_client_frame` |
| `work_tags_request` | An Administrator's library tags for a work, the body of `PUT /api/library/works/{id}/tags` | `bookclerk-library::parse_work_tags_request` |
| `collections_request` | An Administrator's collections for the library, the body of `PUT /api/library/collections` and the stored `core.collections` document | `bookclerk-library::control_plane::parse_collections_request` |
| `connections_request` | A branch Owner's store connections to add to one library, or one to disconnect: the bodies of `POST /api/config/join/connections` and `POST /api/config/join/connections/disconnect` | `bookclerk-library::control_plane::parse_add_connections_request`, `parse_disconnect_request` |
| `pace_request` | A person's pace for one of their store accounts, the body of `POST /api/portal/sources/{source}/connections/{account_id}/pace` | `bookclerk-library::pacing::parse_pace_request` |
| `title_meta_fill` | A signed-in user's title-meta query (the body of `POST /api/discover/title-meta` and each entry of its batch route) and the storefront catalog-detail lookups its store editions and ISBN plan | `bookclerk-discover::check_title_meta_query`, `plan_title_meta_fill` |
| `window_policy` | Requests a page sends on the desktop window's custom scheme, which reach the router with the window's own credential (the operator token or its patron's session cookies) unless refused, the URLs the window is asked to open, and which pages may start the window's live updates | `bookclerk-window-policy` |

Some boundaries need more than a cell:

- **`granted_http`** covers the request head, body framing, chunked bodies
  and the query string.
- **`egress_policy`** fuzzes the JSON wire form. The workerd `egress.js`
  gate is a separate implementation: `egress_bridge` checks its host
  decisions against `EgressPolicy`, and its User-Agent rule is fuzzed in
  JavaScript ([egress bridge User-Agent rule](#egress-bridge-user-agent-rule)).
- **`abi_decode`** goes through `read_any_message`, and
  **`abi_roundtrip`** through `roundtrip_any_message`.
- **`guest_sql_authz`** lowers each policy as the SQLite adapter lowers it.
- **`mux_peer`** covers `Open`, `Data`, `Close` and `Window` frames, their
  lengths and their ids.

### Oracles

Most targets check more than "no panic". `sql_parse` and `mp4_parse` check
only that. The others check:

- **`sql_lower`**: quoted strings and comments survive lowering verbatim,
  except for documented rewrites.
- **`granted_http`**: chunked decoding is split-invariant and agrees with
  an `httparse` reference decoder. The route body reader (framing dispatch,
  byte cap, end of stream) is split-invariant and yields what the declared
  framing promises.
- **`egress_relay_head`**: byte 0 picks a request head (even) or a
  response head (odd). Every head the relay accepts is one `httparse` reads
  the same way (method, target, status). A rewritten request is in origin
  form with exactly one `host` naming the tunnel target, one `connection:
  close` or `upgrade`, none of the stripped proxy and hop-by-hop headers,
  and every other header intact. A final response head carries exactly one
  `connection: close`. The shared oracle is
  `fuzz/oracles/egress_relay_head.rs`, replayed from `bookclerk-workerd`.
- **`workerd_control`**: a port the parser accepts agrees with an
  independent `serde_json::Value` reading, every listen object that reading
  accepts is accepted once re-encoded canonically, and no structured log
  line (the input wrapped as a `console.*` message) yields a port. The
  shared oracle is `fuzz/oracles/workerd_control.rs`, replayed from
  `bookclerk-workerd`.
- **`egress_policy`**: deny allows nothing. Loopback, private and metadata
  addresses need a CIDR in every spelling (trailing dot, fullwidth digits,
  legacy `127.1`, hex and octal IPv4). `*.suffix` never matches `xsuffix`,
  `*` never matches an IP literal and never grants a socket,
  percent-encoded hosts never match, and the JSON round-trips. The
  guest's own `User-Agent` is kept only on hosts an own-agent pattern
  matches, never through a `*` entry however it is spelled, and every
  other request gets the host's agent. The isolate tunnel rule
  (`allows_isolate_tunnel`) is exactly the union of the fetch, redirect and
  TCP rules, on any port. A fetch entry grants only its own port, or 80
  and 443 when it names none. A local name lets only that exact name, or
  the identical literal, reach a local-network address, and never
  loopback or link-local. A pending setting destination grants nothing:
  every rule answers the same without it, and it labels only its own host
  and port.
- **`setting_destination`**: an accepted value derives one destination
  with a port and a host free of wildcards, percent signs and whitespace
  (a name within DNS limits), never from a value with credentials. Deriving its display form gives it
  back, its grant entries are already normalized (the `domains` entry
  names exactly its port), and its scope agrees with an independent
  reading of the host. The shared oracle is
  `fuzz/oracles/setting_destination.rs`, replayed from
  `bookclerk-plugin-manifest`.
- **`egress_bridge`**: for a policy the host can emit (every pattern
  already normalized, every CIDR in its `network/prefix` form), each probe
  host (the grants' names and near misses, local names, `localhost` and
  the metadata name, and IP literals in every range and spelling), on
  granted, default and ungranted ports, goes to `allowsFetch` and
  `allowsRedirectTo` as the URL parser prints it and to `allowsTcp` as
  `canonicalSocketHost` returns it, in QuickJS. QuickJS has
  no URL parser, so the target models both with the `url` crate, and the
  Node replay checks those models against Node's parser and the bridge's
  own `canonicalSocketHost`.
  The bridge never allows what `EgressPolicy` refuses, and on a hostname
  the two agree exactly. The shared oracle is
  `fuzz/oracles/egress_bridge.rs`. Its replay in `bookclerk-workerd`
  pins the Rust verdicts in
  `packages/plugin-sdk/scripts/egress_bridge_vectors.json`
  (`UPDATE_FUZZ_SEEDS=1` rewrites it), and `npm run test:egress-bridge`
  (in the `plugin_sdk_abi` check) replays them against the bridge under
  Node, which also checks the oracle's model of the URL parser. Where a
  newer Node accepts a host the model refuses (Node 26 passes invalid
  `xn--` labels through), the replay holds the gate to the Rust verdicts
  on the raw host instead.
- **`plugin_manifest`**: `format_manifest` round-trips, and a deny manifest
  yields a deny policy. No binding takes the reserved `NETWORK` name, only
  a string setting with `network` carries `default_port`, and a destination
  derived from a network setting's default has a host and a nonzero port.
- **`cron_schedule`**: an accepted schedule round-trips through its
  normalized source, and `next_after` / `latest_at_or_before` agree with a
  minute-by-minute scan of `matches`. The shared oracle is
  `fuzz/oracles/cron_schedule.rs`, replayed from
  `bookclerk-plugin-manifest`.
- **`abi_decode`**: the traversal budget is derived from the input size.
  Structured seeds cover the book records, the metadata replies and the
  cover request and reply (`structured_*.bin`), plus the typed
  `limit_exceeded` envelopes (`limit_error_reply.bin`, `caps_reply_*.bin`,
  `empty_reply_*.bin`, `plugin_error_*.bin`). A guest error's `details`
  are kept only as one JSON object that serializes back to itself.
  Selectors 0 to 5 are the hand-written decoders and the generated table
  follows, so adding a hand-written decoder moves every generated seed's
  selector byte (`structured_book_record_seeds_are_current` rewrites the
  structured seeds with `UPDATE_FUZZ_SEEDS=1`).
- **`db_stream`**: decoding a frame stream in one push and in chunks of
  any size agree (both the same reply, or both refused), an accepted
  reply has no statement over the row cap, and it re-encodes to frames
  that decode to the same reply. A streaming decoder (the one the Rust
  SDK's `iterate()` reads with, which keeps no rows) fed the same chunks
  accepts exactly what one push accepts, hands out every row of it once
  and in order, and finishes with the same reply minus its rows. The
  shared oracle is
  `fuzz/oracles/db_stream.rs`, replayed from `bookclerk-plugin-abi`. The
  TypeScript and Python SDK decoders replay the same seeds and, on every
  run, a fixed set of mutants derived from them with a seeded generator
  (a flipped byte, a truncation, an inserted byte, a duplicated slice),
  holding the first two invariants and typing every refusal.
- **`cover_sink_key`**: a key names a slot exactly when it is the
  canonical decimal spelling of an index below the URL count, read digit
  by digit without `str::parse`, so no two keys name one slot. The shared
  oracle is `fuzz/oracles/cover_sink_key.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`cover_process`**: an input without a JPEG, PNG or WebP signature is
  refused. An accepted cover yields three JPEGs whose markers and frame
  headers, read byte by byte rather than by the `image` crate, show 4:4:4
  sampling, the reported size for the full image, and edges within 2400,
  360 and 128 px that never grow from one size to the next. The shared
  oracle is `fuzz/oracles/cover_process.rs`, replayed from
  `bookclerk-cover`, whose replay test also regenerates the image seeds.
- **`cover_token`**: a token opens only when an independent HMAC-SHA256
  re-signing of its URL reproduces it byte for byte, and the URL is `https`
  with a host; a signed URL round-trips, never opens under another key, and
  a one-byte change is refused. The same input as a Gravatar hash names a
  URL only when it is exactly 64 lowercase hex digits, checked byte by
  byte, and that URL is the hash's picture on `www.gravatar.com` with
  nothing else in it. The shared oracle is `fuzz/oracles/cover_token.rs`,
  replayed from `bookclerk-cover`.
- **`destination_filter`**: the input is the request body. It is accepted
  exactly when an independent reading, built on `serde_json::Value` and a
  separate scan for repeated keys, accepts it: an object with at most a
  `rules` array, each rule an object of exactly `field`, `value` and
  `effect`, no key repeated at any level, at most 64 rules, each value
  trimmed, non-empty, at most 128 bytes and free of NUL, a `patron` value a
  positive user id, a `media_kind` value `book` or `podcast`, a `format`
  value a copy format, a `quality` value a copy quality, and no rule given
  twice. An accepted filter holds the oracle's rules in order, survives a
  JSON round trip, and takes or refuses sample books and sample copies
  exactly as the oracle's reading does. The shared oracle is
  `fuzz/oracles/destination_filter.rs`, replayed from `bookclerk-config`.
- **`intake_settings`**: the input is the request body. It is accepted
  exactly when an independent reading, built on `serde_json::Value` and a
  separate scan for repeated keys, accepts it: at most 16 KiB, one object
  of the documented keys with none repeated, whole numbers in range, the
  documented names for `after_ingest` and `attribute_to`, a positive
  `patron` exactly when `attribute_to` is `owner`, `prune_imported_days`
  only with `after_ingest = move`, and at most 64 distinct ignore patterns
  of 1 to 128 bytes with no path separator or control character, with the
  settings written out with every default at most 12 KiB. Accepted
  settings equal the oracle's reading and survive a JSON round trip. The
  shared oracle is `fuzz/oracles/intake_settings.rs`, replayed from
  `bookclerk-config`.
- **`intake_items`**: the first byte picks the attribution mode and a quiet
  period, and the rest is lines of `key<TAB>size<TAB>signature`. Every
  object is ignored, a stray or a member of the same item as an independent
  reading of the key rules says (ignore patterns through a reference
  matcher of its own), the items hold the oracle's members with the member
  cap flagged exactly when a member past it was listed, the signature does
  not depend on listing order and moves with any size change or a member
  past the cap, and `step` makes an item ready only once the quiet period has
  passed, never past the member cap, and never forgets a queued item. The
  shared oracle is `fuzz/oracles/intake_items.rs`, replayed from
  `bookclerk-intake`.
- **`output_copies`**: the first byte picks the main output's copy and the
  rest is the `copies` array, read as the server reads it (`OutputCopy`'s
  serde derive, then `validate_copies`). It is accepted exactly when an
  independent reading, built on `serde_json::Value` and a separate scan for
  repeated keys, accepts it: at most 8 objects of exactly `format` and
  `quality`, a known format, a quality that is `original`, a bitrate the
  MP3 encoder writes or `v0` to `v9` (optionally `-mono`, any ASCII case,
  trimmed, at most 16 bytes), `original` exactly for M4B and as-delivered
  copies, and no copy repeated or equal to the main output's. An accepted
  list holds the oracle's copies in canonical form and survives a JSON
  round trip. The shared oracle is `fuzz/oracles/output_copies.rs`,
  replayed from `bookclerk-config`.
- **`destination_id`**: the input is the id as received, read as UTF-8
  lossily. It is accepted exactly when it is 1 to 64 bytes, each a
  lowercase ASCII letter, a digit, `_` or `-`, checked byte by byte, so no
  separator, dot or control byte reaches a storage key or a table row. An
  accepted id keeps its text and survives a JSON round trip, and JSON
  refuses whatever the parser refuses. The shared oracle is
  `fuzz/oracles/destination_id.rs`, replayed from `bookclerk-config`.
- **`cache_settings`**: the first byte picks the key. A value is accepted
  exactly when, after ASCII whitespace is trimmed, it is one or more ASCII
  digits whose number, read digit by digit with overflow detection, lies in
  the key's documented range, and the parser returns that number. The
  shared oracle is `fuzz/oracles/cache_settings.rs`, replayed from
  `bookclerk-config`.
- **`relayed_log_line`**: the parsed text is always a trimmed suffix of
  the line, and the level is never above WARN. A level other than INFO
  comes only from a line whose first word (or second word, after a
  timestamp-shaped first word) is exactly `TRACE`, `DEBUG`, `INFO`, `WARN`
  or `ERROR`, read independently token by token; `ERROR` becomes WARN, and
  the prefix is removed. Any other line comes back whole, trimmed, at INFO.
  The shared oracle is `fuzz/oracles/relayed_log_line.rs`, replayed from
  `bookclerk-config`.
- **`diagnostics_submit_reply`**: a reply longer than 4096 bytes is
  refused. Otherwise it is accepted exactly when, read independently as a
  JSON value, it is an object whose `report_id` is a string that is a
  lowercase hyphenated version-4 UUID, checked group by group, and the
  parser returns that string unchanged. The access code comes back exactly
  when `access_code` is a string of 16 characters, each a digit or an
  uppercase letter other than I, L, O and U, and is otherwise dropped
  without refusing the reply. The shared oracle is
  `fuzz/oracles/diagnostics_submit_reply.rs`, replayed from
  `bookclerk-config`.
- **`diagnostics_lookup_reply`**: each input goes through both the lookup
  and the delete reader for one fixed report ID. An answer longer than
  1 MiB is refused. Otherwise, read independently as a JSON value, it is
  accepted exactly when it is an object for that report with every field
  of its type (only `deleted_at_unix_ms`, `report`, `fix` and the fix's
  fields may be absent or null), issue and pull request links start
  `https://`, levels are the five upper-case names and states `open` or
  `closed`. The accepted answer, serialized, equals the expected one
  rebuilt from the value; another report's ID is `OtherReport`. The
  shared oracle is `fuzz/oracles/diagnostics_lookup_reply.rs`, replayed
  from `bookclerk-config`.
- **`cover_wire`**: the first byte picks the request or the reply decoder.
  An accepted frame re-encodes to exactly its own bytes, and an accepted
  reply carries only JPEG-signed images and a nonzero size. The shared
  oracle is `fuzz/oracles/cover_wire.rs`, replayed from `bookclerk-cover`.
- **`tags_read`**: the input is a whole media file. The reader is driven
  twice, supplying each round's spans in order and then reversed, and both
  drives must give the same answer as reading with every byte available up
  front, so the result never depends on how bytes arrive. Every span asked
  for is non-empty and inside the file, within the round and span limits.
  An accepted record passes the host's `TagRecord::validate` and survives
  the worker's `Done` frame unchanged. The shared oracle is
  `fuzz/oracles/tags_read.rs`, replayed from `bookclerk-tags`.
- **`archive_extract`**: the input is an archive, walked twice into memory
  under small caps. The walk is deterministic, its report validates under
  the caps it ran with, every written path stays inside the folder by a
  rule written apart from the crate's (relative, no empty, `.` or `..`
  component, no `\`, `:` or control character), no two paths fold to one
  name, and the sink holds exactly the files the report lists with the
  sizes it states. The shared oracle is `fuzz/oracles/archive_extract.rs`,
  replayed from `bookclerk-archive`.
- **`archive_report`**: the input is a worker's JSON report. A report the
  host accepts names only paths that stay inside the folder by the same
  independent rule, in canonical form and none folding to another, with
  sizes that sum to its total within every cap, and it re-serialises to a
  report that reads back the same. The shared oracle is
  `fuzz/oracles/archive_report.rs`, replayed from `bookclerk-archive`.
- **`tags_wire`**: the first byte picks the request or the reply decoder.
  An accepted request, `Need` or `Failed` frame re-encodes to exactly its
  own bytes; a `Need` names one to 64 non-empty, non-overflowing spans; a
  `Done` record re-encodes to a frame that decodes to the same record. The
  shared oracle is `fuzz/oracles/tags_wire.rs`, replayed from
  `bookclerk-tags`.
- **`model_pack`**: the first byte picks the reader: `0` reads the rest as
  a model description, any other value reads it as a row pack whose rows
  have that many bytes. An accepted description names only files that stay
  inside the model directory by a rule written apart from the crate's,
  each once and none named `model.json`, keeps its limits, and writes back
  to JSON that reads as the same description. A row pack's verdict equals
  a layout check written apart from the crate's; an accepted pack gives
  every listed token the bytes at the position the layout states, nothing
  for a token it does not list, and re-encodes to exactly its own bytes.
  The shared oracle is `fuzz/oracles/model_pack.rs`, replayed from
  `bookclerk-model-pack`.
- **`media_decode`**: the input is a whole audio file. It is decoded at
  the source's channel count twice and once mixed to mono. An accepted
  stream has a sample rate from 1 Hz to 768 kHz and one or two channels,
  and every chunk is whole frames; the same bytes always give the same
  PCM; and the mono decode accepts exactly the files the source decode
  does, with the same rate and length. A plain 16-bit PCM WAV must decode
  to exactly the samples an independent parser in the oracle reads from
  it. Seeds cover every container and codec the worker reads, including
  HE-AAC, HE-AAC v2, Ogg Opus (mono and stereo), Ogg Vorbis, and the
  FFmpeg formats (WMA 1 and 2, raw AC-3 and E-AC-3, E-AC-3 in MP4, raw
  AMR-NB and AMR-WB, AMR-WB in 3GP). The fuzz build turns on the `libav`
  feature, so the target drives FFmpeg's demuxers and decoders through the
  shim; FFmpeg itself is not instrumented for coverage (OSS-Fuzz fuzzes it
  upstream). The shared oracle is
  `fuzz/oracles/media_decode.rs`, replayed from `bookclerk-media`.
- **`media_keep_codec`**: the input is one audio part, packaged twice
  over into one M4B keeping its audio. A refused part leaves no file
  behind. An accepted M4B has two chapters, the first at 0 ms; the
  independent ISO-BMFF parser in `bookclerk-mp4` reads it, finds an Opus,
  FLAC, ALAC, E-AC-3 or AC-4 sample entry, and every sample lies inside the
  file; the second half of the sample table repeats the first; and the
  same bytes always give the same file. Seeds are Ogg Opus, FLAC and ALAC
  parts, plus AAC and damaged files the packager refuses. The shared
  oracle is `fuzz/oracles/media_keep_codec.rs`, replayed from
  `bookclerk-media`.
- **`media_pcm_wire`**: the first byte, modulo 3, picks a request body, a
  reply body, or the worker's whole output. An accepted request or reply
  re-encodes to exactly its own bytes, and a reply's fields are within the
  wire's limits, checked against the constants rather than the decoder's
  own code. The whole output is fed to `ReplyReader` in pieces whose sizes
  come from the input: the replies it yields re-encode, concatenated, to
  exactly the bytes it consumed, it yields nothing after an error, and
  every `Pcm` that `ReplyOrder` admits holds whole frames of the `Format`
  it admitted first. The shared oracle is `fuzz/oracles/media_pcm_wire.rs`,
  replayed from `bookclerk-media`.
- **`cache_headers`**: the first byte, modulo 4, picks a mode. A built
  `If-None-Match` list of well-formed tags matches exactly when one of
  them is the current tag, strong or weak. Any raw header that matches,
  other than `*`, contains the quoted tag, and padding it with whitespace
  never changes the answer. A built `Cache-Control` list (with `Age`) gets
  the storage decision and freshness lifetime the oracle works out on its
  own. Any raw set of upstream headers gives a lifetime between the floor
  and ceiling, is refused storage only when `no-store` appears, and keeps
  an `ETag` only as the trimmed header. The shared oracle is `fuzz/oracles/cache_headers.rs`,
  replayed from `bookclerk-cover`.
- **`abi_roundtrip`**: a value the decoder accepts re-encodes, re-decodes
  and compares equal (`read(write(v)) == v`).
- **`scan_page`**: the input splits into the cursor the host sent, the
  account it asked for and a `ScanPage` message. The host accepts the page
  exactly when an independent check of every rule agrees: at most
  `MAX_SCAN_PAGE_BOOKS` books and as many removed ids, a cursor and token
  within `MAX_SCAN_CURSOR_BYTES`, a next cursor that is empty or differs
  from the one sent, books for that account only, no blank product or
  removed id, every book naming its three kinds with a work kind and
  carrier inside a fixed audio declaration, and refreshed credentials that are absent, empty, or one
  JSON object within `MAX_REFRESHED_CREDENTIAL_BYTES` (the same
  `validate_refreshed_credentials` check the host runs on a
  `PlainFetch` reply's refreshed credentials). An accepted
  page round-trips through the codec and is accepted again. The shared
  oracle is `fuzz/oracles/scan_page.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`quality_offers`**: byte 0 is how many title ids the host sent and the
  rest is a `QualityOffersResult` message. The host accepts the reply
  exactly when an independent check agrees: no more answers than titles
  sent, every found offer within `MAX_OFFER_CHANNELS`,
  `MAX_OFFER_SAMPLE_RATE_HZ` and `MAX_OFFER_BITRATE_KBPS` with an AAC
  profile only on AAC, and refreshed credentials that are absent, empty,
  or one JSON object within `MAX_REFRESHED_CREDENTIAL_BYTES`. An accepted
  reply round-trips through the codec and is accepted again. The shared
  oracle is `fuzz/oracles/quality_offers.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`plain_fetch`**: the input is a `PlainFetch` message. The host accepts
  it exactly when an independent check agrees, against a fixed declaration
  that fetches audio: the carrier is audio, every file has a role and a
  non-blank path, there is at most one `whole` file and one `cover`, and
  the reply lists `part`s or a `whole` file but not both. An accepted
  reply round-trips through the codec and is accepted again. The shared
  oracle is `fuzz/oracles/plain_fetch.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`metadata_file_record`**: the input is a `MetadataFileRecord` message.
  The host accepts it exactly when an independent restatement of every
  rule agrees: no field or credit role listed twice, a value only for a
  field in `present`, each credit's role in `creditRoles`, labels on one
  non-blank line within their caps, a partial ISO date, list and chapter
  caps, and chapters in start order with no depth jump. An accepted
  record is then checked against a fixed `abs_metadata_json` dialect,
  and passes exactly when it states only that dialect's fields and roles.
  An accepted record round-trips through the codec and is accepted again.
  The shared oracle is `fuzz/oracles/metadata_file_record.rs`, replayed
  from `bookclerk-plugin-abi`.
- **`notifier_reply`**: byte 0 modulo 2 picks a `NotifySendReply` message
  (0) or an address document as text (1). A reply is delivered exactly when
  it is the `ok` arm, keeping a provider id only when it is a non-empty line
  within the field cap; it is retried exactly for `rate_limited`,
  `unavailable`, `deadline_exceeded` and `cancelled`, waiting only on
  `rate_limited` and never past an hour; and every reason is the error
  text with control, line-separator and bidi characters blanked, cut to
  512 bytes on a character boundary. The reply round-trips through the
  codec. An address document is accepted exactly when it is one JSON
  object of at most 16 distinct identifier keys with one-line string values
  within the field cap, re-serialises to text that parses back equal, and
  fits a fixed `email` (required) and `name` field list exactly when it has
  a non-blank `email` and no other key. The shared oracle is
  `fuzz/oracles/notifier_reply.rs`, replayed from `bookclerk-plugin-abi`.
- **`notify_raise`**: byte 0 modulo 2 picks the bridge's JSON body (0) or a
  Cap'n Proto `NotifyRaiseParams` (1). The raise is accepted exactly when
  an independent restatement agrees: a local type id, at most 25 fields
  with non-blank one-line names, a printable patron id, a link path that
  starts with exactly one `/` and has no space, backslash or control
  character, a one-line group key, and an alert key exactly when the alert
  action is not `none`. An accepted raise round-trips through the codec and
  is accepted again. The shared oracle is `fuzz/oracles/notify_raise.rs`,
  replayed from `bookclerk-plugin-abi`.
- **`ai_run_reply`**: byte 0 modulo 2 picks a reply to a run (0) or a model
  listing (1). A run case carries the number of texts sent and the vector
  length the model listed ahead of an `AiRunReply` message. The reply is
  accepted exactly when an independent restatement agrees: it names no
  model, carries the listed vector length and revision, holds exactly one
  vector of finite numbers per text, and its fallback indexes ascend
  strictly inside the input. An accepted reply splits into that many
  vectors, and packing them gives its bytes back. A listing is accepted
  exactly when it has at most 64 models, each id once and well formed, with
  a printable revision, well-formed languages listed once, a vector length
  from 1 to 4096 and a token limit above zero. Both round-trip through the
  codec. The shared oracle is `fuzz/oracles/ai_run_reply.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`ai_run`**: byte 0 modulo 2 picks the bridge's JSON body (0) or a
  Cap'n Proto `AiRunParams` (1). The run is accepted exactly when an
  independent restatement agrees: a model name of at most 192 bytes that is
  `@<plugin id>/<model id>` or `@library/text-embeddings`, and 1 to 64
  texts, none empty and none over 16 KiB. An accepted name prints back as
  written, the same input under the bare model id passes the check the host
  runs before the model plugin sees it, and the run round-trips through the
  codec. The shared oracle is `fuzz/oracles/ai_run.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`notify_address_body`**: the input is the `address` object. It is
  accepted exactly when an independent reading that keeps every entry,
  repeats included, finds one JSON object whose values are all strings and
  whose keys are all different, and the accepted fields are the same as
  that reading's. An accepted address written out again reads back the
  same. The shared oracle is `fuzz/oracles/notify_address_body.rs`,
  replayed from `bookclerk-plugin-abi`.
- **`notify_cursor`**: the input is the token. It is accepted exactly
  when it is at most 512 bytes of unpadded base64url whose bytes are one
  JSON object with exactly the keys `created_at` and `id`, each written
  once, each a string of at most 128 bytes with no U+0000, as the
  oracle's own base64url
  decoder and an untyped reading of the JSON agree. An accepted token
  re-encodes to one that decodes to the same cursor. The shared oracle is
  `fuzz/oracles/notify_cursor.rs`, replayed from `bookclerk-library`.
- **`event_read`**: byte 0 modulo 4 picks a `/events/read` JSON body (0),
  a bare cursor (1), or a Cap'n Proto `EventReadRequest` (2) or
  `EventReadPage` (3). The body parser accepts exactly the JSON objects whose
  keys are request fields, and an accepted request round-trips through
  JSON. Validation against a fixed consent agrees with an independent
  restatement of every rule: the error code, or the resolved start, types
  and limit. The cursor decoder accepts exactly the canonical cursors a
  hand-written decoder accepts, and an accepted cursor re-encodes to the
  same text. A Cap'n Proto request or page that the RPC codec accepts
  survives `write` then `read` unchanged and stays inside the cursor and
  list bounds. The shared oracle is `fuzz/oracles/event_read.rs`, replayed
  from `bookclerk-plugin-abi`.
- **`storage_reply`**: byte 0 modulo 6 picks a Cap'n Proto `moveMany`
  page (0), `deleteMany` result (1), `headMany` result (2), `changes` page
  (3), hinted `list` page (4) or `translateKeys` result (5). A decoded reply survives encode then
  decode unchanged, and each validator accepts the reply, against a fixed
  request, exactly when an independent restatement of its rules does: one
  outcome per sent key in order, prefix pages under the prefix with a
  cursor that advances, change pages within the page and cursor bounds,
  and one translated key per host key, each relative, at most 4096 bytes,
  with no control characters and no empty, `.` or `..` segment. A
  per-key error whose code is unreadable decodes as an `unknown` failure,
  never as success. The shared oracle is `fuzz/oracles/storage_reply.rs`,
  replayed from `bookclerk-plugin-abi`.
- **`s3_event`**: byte 0 picks the destination's key prefix (even: none,
  odd: `library/`) and the rest is one queue message. Parsing never panics
  and answers the same twice; a body over 1 MiB is refused as too large;
  every reported change has a non-empty key without NUL, within 1,024
  bytes, with listing fields only on an upsert. Whenever the parser accepts
  a message, an independent walk of the same JSON, with its own
  percent-decoder, finds exactly the same changes in the same order. Keys
  are form-decoded only in S3 event records (direct or inside an SNS
  envelope); EventBridge keys arrive decoded. A key outside the bucket or
  prefix is skipped before it is checked, so a broken key elsewhere in the
  bucket does not fail the message. The
  shared oracle is `fuzz/oracles/s3_event.rs`, replayed from
  `bookclerk-storage`.
- **`r2_event`**: byte 0 picks the boundary (even: one R2 event
  notification, odd: a Queues pull reply) and, with bit 1, the
  destination's key prefix (clear: none, set: `library/`). Parsing never
  panics and answers the same twice; an input over its cap (1 MiB for an
  event, 24 MiB for a reply) is refused as too large. An accepted event
  yields at most one change, with a non-empty key without NUL, within
  1,024 bytes, listing fields only on an upsert and no version or
  sequencer, and an independent walk of the same JSON finds exactly that
  change; events for another account or bucket, or keys outside the
  prefix, are skipped before the key is checked. An accepted reply says
  `success: true`, lists at most 100 deliveries, one per message, each
  with the message's own non-empty lease id within 4,096 bytes and a body
  that is either the text as sent or, read by the oracle's own base64
  decoder, JSON; each body is then checked as an event. The reply, each
  message, an event and its object must be JSON objects. The shared oracle
  is `fuzz/oracles/r2_event.rs`, replayed from `bookclerk-storage`.
- **`b2_reply`**: byte 0 modulo 9 picks the reader: an authorization (0),
  a bucket list (1), an upload URL (2), one file version (3), a file-name
  page (4), a file-version page (5), an uploaded part (6), an error reply
  with bytes 1 and 2 as its status (7), or download headers, one
  `name: value` per line (8). Reading never panics and answers the same
  twice. An error reply always reads, with a non-empty code, and code and
  message cut to 1,024 bytes without control characters. An accepted
  reply agrees with an independent walk of the same JSON (token, file
  names and ids, list lengths, part number); its URLs are plain `https`;
  every file name passes the oracle's own copy of B2's naming rules; a
  file-name page's continuation is past every listed name; a
  file-version page continues with a name and a file id together, so it
  may continue at the last listed name, and lists each name's versions
  newest first; every SHA-1 is 40 lowercase hex digits; an error code
  other than `unknown` is exactly the one the error object sent; and accepted download headers name a file id
  and a body no longer than the file. Percent-encoding any text matches
  the oracle's own encoder and decodes back to the text. The shared
  oracle is `fuzz/oracles/b2_reply.rs`, replayed from `bookclerk-storage`.
- **`socket_request`**: byte 0 modulo 3 picks a socket URL (0), a Cap'n
  Proto `SocketConnectRequest` (1) or a `SocketMessage` (2). Every URL the
  parser accepts is one a WHATWG URL parser (the `url` crate) reads as the
  same scheme, host and port with no credentials or fragment, so the
  network grant and the connection can't disagree about the target.
  Connect validation accepts exactly the requests whose URL parses and
  that an independent restatement of the header, subprotocol, heartbeat
  and attachment rules accepts; heartbeat matching answers exactly the
  frames equal to a declared request; delivery checks agree with the
  restated id, frame and attachment bounds; and a decoded message
  survives `write` then `read` unchanged. The shared oracle is
  `fuzz/oracles/socket_request.rs`, replayed from `bookclerk-plugin-abi`.
- **`origin_request`**: byte 0 modulo 4 picks a framed `POST /origin/fetch`
  body (0), a request head's JSON (1), a response head's JSON (2) or an
  ingress origin (3). Splitting waits for more bytes exactly while the frame
  is incomplete, refuses exactly the declared lengths past the head cap, and
  otherwise returns the declared head and every byte after it, so the
  request body starts at the right byte and a plugin can't make the host
  buffer without bound. A request head is accepted exactly when an
  independent restatement of the method, origin-form target, header and
  client-address rules holds; an accepted head keeps its method, target and
  client, drops exactly `host` and the forwarding fields, and frames back to
  itself. Response heads agree with the restated status and header rules.
  An origin is accepted exactly when the restated host-name rules hold, and
  a WHATWG URL parser (the `url` crate) reads every accepted origin as
  `https` and the same host with no port, user info, path, query or
  fragment. The shared oracle is `fuzz/oracles/origin_request.rs`, replayed
  from `bookclerk-plugin-abi`.
- **`socket_broker`**: the input is a script of operations on the broker's
  socket table (connect requests, handshake outcomes, frames and closes
  from the server, sends, attachments and closes from the plugin), checked
  against an independent model. The table never holds more than 8
  sockets, pending ones included; ids are valid and never reused; a frame
  from the server is answered by the broker exactly when it equals a
  declared heartbeat, closes the socket with 1009 exactly when it is over
  the frame cap, and is otherwise delivered with the socket's current
  attachment; nothing reaches the plugin for a pending or ended socket; a
  socket is reported closed once, with its last attachment; and the
  listing matches the model. The shared oracle is
  `fuzz/oracles/socket_broker.rs`, replayed from `bookclerk-workerd`.
- **`socket_route`**: the first byte picks the operation and the rest is
  the JSON body. An unknown operation is refused as not found, and nothing
  else is; a body that is not a JSON object, or that carries a field the
  operation does not define, is refused as invalid; every accepted call is
  inside restated ABI rules (socket ids, frame and attachment sizes, close
  codes and reasons, and the connect checks the broker applies); and an
  accepted call written back out in the route's form parses the same way.
  The shared oracle is `fuzz/oracles/socket_route.rs`, replayed from
  `bookclerk-workerd`.
- **`webhook_route`**: the first byte picks the operation and the rest is
  the JSON body. An unknown operation is refused as not found, and nothing
  else is; a body that is not a JSON object, or that carries a field the
  operation does not define, is refused as invalid; every accepted call is
  inside restated ABI rules (names, batch size, visibility timeout, lease
  ids, list sizes, no lease both acknowledged and retried); and an
  accepted call written back out in the route's form parses the same way.
  The shared oracle is `fuzz/oracles/webhook_route.rs`, replayed from
  `bookclerk-workerd`.
- **`webhook_message`**: byte 0 picks a pull request, an ack request or a
  delivery, and the rest is the Cap'n Proto message. What decodes
  re-encodes to an equal value, and the host's pull and ack checks accept
  a request exactly when it is inside the rules the oracle restates. The
  shared oracle is `fuzz/oracles/webhook_message.rs`, replayed from
  `bookclerk-plugin-abi`.
- **`webhook_request`**: byte 0 picks the row's signature rule and whether
  the oracle adds a correct signature; the rest is the secret, the body
  and header pairs. A body over the cap is refused as too large before
  anything else; a signed row without a secret is unavailable; a signed
  request is accepted only when its one signature header carries the
  HMAC-SHA256 the oracle computes from SHA-256 alone (RFC 2104), and the
  correct signature is accepted unless a header repeats or is malformed;
  and the kept headers are exactly the ones sent among `content-type` and
  the row's list, unchanged and well formed. The shared oracle is
  `fuzz/oracles/webhook_request.rs`, replayed from `bookclerk-workerd`.
- **`guest_sql_authz`**: every table, column, function and schema action
  that SQLite's own authorizer reports for an admitted statement is inside
  the policy. The shared oracle is `fuzz/oracles/guest_sql_authz.rs`,
  replayed from `bookclerk-library`.
- **`mux_peer`**: the link settles within a bound once the peer's bytes
  end, delivers no more than the peer sent, accepts no more streams than
  the peer could open, and leaves no task behind. The shared oracle is
  `fuzz/oracles/mux_peer.rs`, replayed from `bookclerk-plugin-sdk`.
- **`library_resolve`**: decodes up to 64 listings from small pools of
  titles, authors and identifiers, so they collide, and records each one
  into an in-memory catalog, either held or as a catalog listing (a store
  answer nobody holds). A catalog listing is placed exactly where a scan
  holding it would be (same listing, edition, link and work reason as the
  held plan on the same rows), passes the same placement checks as a held
  listing, never gains a holding and never announces a holding or its own
  new link. After every step one strong identifier maps
  to one edition; a weak identifier alone never joins editions of
  another media kind, work kind or an incompatible expression; strong
  identifiers naming different editions are never merged and the conflict
  is recorded; a work found by identifier or text match has the listing's
  kind, and an episode's work shares its show. Resolving any listing
  again changes nothing, except that an episode recorded before its show
  gains the show once, and a work stored without a matcher key gains one
  once no other work holds it. The oracle is
  `bookclerk_resolve::fuzzing::run_case`, replayed from `bookclerk-resolve`.
- **`node_frame`**: an accepted frame is within the size limit and the
  frame version, and serializes and parses back to an equal frame (unless
  its serialized text grows past the limit, as `1e9` written out does). Every
  call number in `acquire.targets` is 1 to 16 ASCII letters and digits,
  checked byte by byte, and every target whose destination list passes
  its validator names only destinations its plan lists, each once and in
  the plan's order. A `catalog.ask` or `catalog.found` that passes
  its validator names at most 100 works, each once, by plain correlation
  keys; its identifiers are plain ASCII with a marketplace exactly on an
  ASIN, and each answer lists 1 to 8 distinct editions with a title. A
  `requests.claimed` that passes its validator holds at most 16 requests,
  each job once, with a valid work and a plain store and product id, and
  a `requests.finish` that passes its validator names a plain job id
  and a positive generation. A
  `window.page` that passes its validator carries at most 100 works, each
  once, with plain identifiers, 1 to 8 distinct editions with a title,
  each owned, or reachable and then neither the person's nor with a copy,
  a copy (where one is stated) with a lowercase media type, a
  bitrate of 1 to 20000 kbit/s, a short lowercase source store and a
  plain version, and a plain next cursor (up to 64 letters, digits and `-`)
  sorting past the one asked with. A `scan.removed` or
  `scan.pass_end` that passes its validator names an account and carries
  at most 500 product ids, each non-blank, at most 512 bytes and free of
  control characters, or a sync token of at most 4096 bytes with no
  control characters. A file of an `upload.grant` or `catalog.upload`
  that passes its validator states a probe only with a bitrate of at most
  20,000 kbps and a plain store id. A `copy.grant` that passes its
  validator names a plain store id, a lowercase marketplace and a product
  id with no control characters or outer whitespace. A `copy.granted`
  that passes its validator carries a lowercase hyphenated UUID as its
  copy id, a token of 1 to 1024 base64url characters, a life of one
  second to a day, and 1 to 1000 files with distinct relative names
  (at most 512 bytes, no `.` or `..` segment, backslash, control
  character or drive prefix), each at most 1 TiB, exactly one of them the
  primary audio. The `copy_*` seeds' names say whether the receiver takes
  the frame, and the replay test checks each against its name. Seeds cover `accounts.update`, `accounts.updated`,
  `scan.removed`, `scan.pass_end`, a `work` frame with scan tokens, and
  `acquire.targets` with a destination subset, an empty list and a list
  that does not fit its plan. The shared oracle is `fuzz/oracles/node_frame.rs`,
  replayed from `bookclerk-node-proto`.
- **`node_account_bundle`**: an accepted bundle is within the size limit,
  has the bundle version and names the library and node it was opened
  for. It carries at most the account and secret limits; every text field
  is non-empty, within its limit, free of control characters and
  surrounding whitespace; every secret is 1 byte to its limit; no account,
  and no secret within an account, repeats. These are checked character by
  character in the oracle, not through the parser's own rule. An accepted
  bundle serializes and parses back to an equal bundle. The shared oracle
  is `fuzz/oracles/node_account_bundle.rs`, replayed from
  `bookclerk-node-proto`.
- **`plan_authz`**: decodes a small library (store accounts on two plugins
  whose ids and labels collide, who each is linked to, library rows and
  plugin instances) and one Member's scan or acquire request into an
  in-memory database, then plans it. Every planned job names an account,
  and every account its needle reaches at run time (id or label, ignoring
  ASCII case, within the pinned instance's plugin) is linked to that
  Member, checked against the oracle's own model rather than the planner's
  queries. A refusal is `Forbidden` or `Invalid`. The shared oracle is
  `fuzz/oracles/plan_authz.rs`, replayed from `bookclerk-library`.
- **`clerk_authorization`**: reads the header value byte by byte. It
  yields a token exactly when it is the scheme `Bookclerk-Clerk` in any
  ASCII case, one space, and 43 characters from `A-Z`, `a-z`, `0-9`, `-`
  and `_`, with nothing else, and the token is those 43 bytes. The shared
  oracle is `fuzz/oracles/clerk_authorization.rs`, replayed from
  `bookclerk-node-proto`.
- **`clerk_authorize`**: reads the query as form-encoded pairs. It
  parses exactly when no parameter repeats and `client_id`,
  `redirect_uri`, `response_type` and `code_challenge` are present, and
  each field is the decoded value sent. It is accepted exactly when the
  client is `bookclerk-clerk`, the response type is `code`, the
  challenge is S256 with 43 base64url characters, the scope is
  `library:member`, the redirect URI is `https` with a host or `http` on
  a loopback address or `localhost` (no user info, no fragment), the
  clerk name is 1 to 64 bytes, not blank and without control
  characters, and any state is at most 512 bytes without control
  characters. The shared oracle is `fuzz/oracles/clerk_authorize.rs`,
  replayed from `bookclerk-node-proto`.
- **`clerk_token_request`**: the first byte picks the stored code (the
  clerk's, the branch client's, or one with the `plain` method) and
  the rest is the body. The body parses exactly when it is one JSON
  object with no repeated keys and exactly the string keys `code`,
  `code_verifier` and `redirect_uri`, and each field is the value sent.
  The exchange matches exactly when the code is the clerk's, the
  method is S256, the redirect URI is the stored one, and the trimmed
  verifier is not empty and hashes to the stored challenge (checked
  against RFC 7636's example pair). The shared oracle is
  `fuzz/oracles/clerk_token_request.rs`, replayed from
  `bookclerk-node-proto`.
- **`clerk_token_answer`**: the input is the answer body, checked
  against the body read as an untyped JSON value. It parses exactly when
  it is at most 8 KiB and one object, no field it reads is written twice,
  `token` is 43 base64url characters, `library_id` is a library id,
  `user.id` is a positive integer, `user.display_name` (optional) is at
  most 128 bytes with no control characters, and `idle_secs` is from 1
  second to a year; other keys are ignored, and each field is the value
  sent. The shared oracle is `fuzz/oracles/clerk_token_answer.rs`,
  replayed from `bookclerk-node-proto`.
- **`copy_range`**: the input is the file's size (eight bytes, big
  endian) and then the header as sent. A part the parser answers lies
  inside the file (at least one byte, ending at or before the end), so a
  read never passes the file; only a header that is `bytes=`, digits and
  exactly one `-` gets a part or "unsatisfiable", and anything else gets
  the whole file; and the answer equals the one the oracle works out by
  reading the header a second way (digits folded into a wide integer).
  Seeds named `part-*` must parse as a part and the others must not. The
  shared oracle is `fuzz/oracles/copy_range.rs`, replayed from
  `bookclerk-node-proto`.
- **`upload_part`**: the input is the file's declared size (eight bytes,
  big endian) and then the header as sent. A part the parser answers lies
  inside the file (at least one byte, ending at or before the end), so the
  owner never writes past the declared size; only `bytes <first>-<last>/<size>`
  with canonical decimal numbers and the declared size is a part, and
  only `bytes */<size>` a status query, so each has one spelling (the
  answer names the header back exactly); and the answer equals the one
  the oracle works out by reading the header a second way (digits
  folded into a wide integer). Seeds named `part-*` must parse as a
  part, `status-*` as a status query, and the others must be refused.
  The shared oracle is `fuzz/oracles/upload_part.rs`, replayed from
  `bookclerk-node-proto`.
- **`tunnel_policy`**: the input is one byte choosing the exposure (even:
  branches, odd: the whole library) and then the path as sent. The
  normalized path is what the router matches (one leading slash, no
  trailing slash) and normalizing it again changes nothing; the
  operator-only paths are refused under both exposures; the whole-library
  exposure refuses nothing else; and the answer equals the one the oracle
  works out by comparing path segments rather than string prefixes. Seeds
  named `served-*` must be served, `operator-*` refused as operator-only,
  and `refused-*` refused as not exposed. The shared oracle is
  `fuzz/oracles/tunnel_policy.rs`, replayed from `bookclerk-node-proto`.
- **`copy_answer`**: the input is the byte the reader asked to resume
  from and the file's size (eight bytes each, big endian) and then the
  answer as received: the head, the blank line that ends it (CRLF CRLF)
  and, if a seed wants them, first bytes of the body. A seed whose head
  has no blank line after it is read as an answer that has not ended, and
  is refused. The head ends before the first blank line, which the oracle
  finds by a second scan one byte at a time; it is refused when that is
  past 16 KiB; and every shorter run of the same bytes finds the same
  head once it holds the blank line and none before, so where the
  library's writes fall never moves a byte between the head and the
  file. A body the parser
  answers ends exactly at the file's end and starts at byte 0 or at the
  byte asked for, and only a `206` starts above 0, so a reader never
  writes past the size the grant stated or leaves a gap. A head is
  refused when it is not printable ASCII lines ended by
  CRLF, has no `HTTP/1.0` or `HTTP/1.1` status line with a status from
  100 to 599, has a header line without a colon or whose name is not an
  HTTP token, states a
  transfer encoding, or repeats or misstates `Content-Length` or
  `Content-Range`; a `200` is a body exactly when its length is the
  file's size and it states no range; a `206` exactly when a byte inside
  the file was asked for and the range and length are that byte to the
  end; a `416` that states a range must state `bytes */<size>`; every
  other status is an answer without file bytes. The answer
  equals the one the oracle works out by reading the head a second way
  (bytes compared one by one, digits folded into a wide integer). Seeds
  named `body-*` and `status-*` must parse as that and the others must be
  refused. The shared oracle is `fuzz/oracles/copy_answer.rs`, replayed
  from `bookclerk-node-proto`.
- **`clerk_socket_frame`**: the first byte picks the direction (even:
  clerk to library; odd: library to clerk) and the rest is the frame,
  checked against the frame read as an untyped JSON value. A clerk frame
  parses exactly when it is at most 4 KiB, one object with no repeated
  keys and `v` the integer 1, and is either `books` with `after` (a
  cursor string: empty, or up to 64 letters, digits and `-`) and no
  listing field, or `copy.grant` with a well-formed `store`, `product_id`
  and optional `marketplace` and no `after`. A library frame is refused when it is not one
  object, repeats a key, has another `v` or an unknown `type`, or carries
  another type's field; `hello` and `changed` parse exactly when `topics`
  holds at most 16 well-formed names, and keep only the ones the clerk
  knows; `error` parses exactly for a known `code`; an accepted
  `books.page` passes `window_page_problem`; `copy.granted` parses
  exactly when its listing is well formed, `copy_id` is a lowercase UUID,
  `token` is 1 to 1024 base64url characters, the life is 1 to 86 400
  seconds, `copy` is present and well formed
  (`WindowCopy::is_well_formed`), and the files are 1 to 1000 well-formed files with distinct
  names and exactly one primary audio. Every accepted frame
  round-trips through its encoder, unless the encoded text is over the
  size limit. The shared oracle is
  `fuzz/oracles/clerk_socket_frame.rs`, replayed from
  `bookclerk-node-proto`.
- **`instance_config`**: the first byte picks the path, against a fixed
  schema with a string `name` and a table `mappings` (`library` required,
  `prefix`, `watch` with a default, `mode` an enum). The settings object
  is read as an untyped JSON value and accepted exactly when every key is
  declared and every value fits its kind, rows included, with strings of
  at most 1024 bytes and no NUL; an accepted table normalizes once and
  then stays the same, with defaults filled. Row text is split by the
  oracle's own reading of `|`, `\|` and `\\` and accepted exactly when its
  cells fit their columns and name `library`, giving one row of exactly
  those cells. The shared oracle is `fuzz/oracles/instance_config.rs`,
  replayed from `bookclerk-library`.
- **`job_cap_request`**: reads the body as an untyped JSON value. It is
  accepted exactly when it is one object with no repeated keys and no keys
  besides `library_id` (a string) and `max_jobs` (`null` or a whole number
  from 0 to 16), both present; the parser then returns the trimmed id and
  that cap, and otherwise refuses it as `Invalid`. The shared oracle is
  `fuzz/oracles/job_cap_request.rs`, replayed from `bookclerk-library`.
- **`branch_request`**: reads the body as an untyped JSON value. It is
  accepted exactly when it is one object with no repeated keys and no keys
  besides `work_id` (a string, required) and `node_id` (absent, `null` or
  a string), where the trimmed `work_id` is 1 to 64 ASCII letters, digits
  and `-`, and a trimmed `node_id` is 1 to 58 lowercase ASCII letters,
  digits, `.`, `_` and `-`. The parser then returns those trimmed ids,
  and otherwise refuses it as `Invalid`. The download request parser reads
  the same bytes: it accepts exactly the bodies the branch request parser
  accepts that have no `node_id` key at all, with the same trimmed work
  id, and refuses the rest as `Invalid`. The shared oracle is
  `fuzz/oracles/branch_request.rs`, replayed from `bookclerk-library`.
- **`title_meta_fill`**: the first byte declares `detailByProductId` and
  `detailByIsbn` for four fake stores; the rest is the query body, read as
  untyped JSON. An object body is served exactly when its known fields
  have the documented types, none is written twice, it names at most 16
  store editions (each a `source` and `product_id` string), and its
  trimmed title, ASIN and ISBN are not all empty. A served query plans at
  most three lookups: at most two by product id, in edition order, at
  listing stores that declared `detailByProductId`, then by ISBN (or an
  ISBN-shaped ASIN) at the stores that declared `detailByIsbn`, never the
  same store and id twice. Positional (array) forms are left to the typed
  parser, and their plan is still checked. The shared oracle is
  `fuzz/oracles/title_meta_fill.rs`, replayed from `bookclerk-discover`.
- **`members_books_request`**: reads the body as an untyped JSON value.
  It is accepted exactly when it is one object with no repeated keys and
  exactly the keys `node_id` (a string) and `acquire` (a boolean), where
  the trimmed `node_id` is 1 to 58 lowercase ASCII letters, digits, `.`,
  `_` and `-`. The parser then returns that trimmed id and the boolean,
  and otherwise refuses it as `Invalid`. The shared oracle is
  `fuzz/oracles/members_books_request.rs`, replayed from
  `bookclerk-library`.
- **`upload_manifest`**: the first byte picks the input (`m` for a
  manifest, `o` for an `Upload-Offset` value). A manifest is accepted
  exactly when it is JSON with no repeated keys holding `files` (an object
  with only that key, or the one-element array form serde also reads),
  at most 10,000 files, each an object of `path` (a string), `size` (an
  unsigned integer) and optional `sha256` (`null` or 64 hex digits) and
  nothing else, or the two- or three-element array form, with every path
  admitted by the archive path policy. The specs keep order, sizes and
  lower-cased digests, and no admitted path is absolute, empty, holds a
  `.`, `..` or empty component, a backslash or a NUL. An offset is
  accepted exactly when it is 1 to 19 ASCII digits that fit `i64`. The
  shared oracle is `fuzz/oracles/upload_manifest.rs`, replayed from
  `bookclerk-library`.
- **`member_controls_request`**: the first byte picks the body (`d` for
  the default, `u` for a patron's overrides) and the oracle reads the rest
  as an untyped JSON value. The default is accepted exactly when it is one
  object with no repeated keys whose keys are among `link_accounts`,
  `download`, `edit_metadata`, `upload`, `request_books` and `see_prices`,
  each a boolean; a control left out is allowed. A patron's body is
  accepted exactly when it is one object with no repeated keys and exactly
  the key `overrides`, an object of those keys with boolean or `null`
  values; a control left out or `null` follows the default. The parser
  then returns exactly those values, and otherwise refuses the body as
  `Invalid`. The shared oracle is `fuzz/oracles/member_controls_request.rs`,
  replayed from `bookclerk-library`.
- **`patron_scope_request`**: the first byte picks the body (`d` for the
  default scope, `u` for a user's) and the oracle reads the rest as an
  untyped JSON value. A scope is accepted exactly when it is one object
  with no repeated keys at any depth and at most the key `rules`, an array
  of at most 16 rules, each exactly `field` (`genre`, `series`, `author` or
  `narrator`), `value` (a string, 1 to 256 bytes once trimmed, no NUL) and
  `effect` (`include` or `exclude`), with no two rules sharing field,
  effect and lowercase trimmed value, and the trimmed rules come to at
  most 1,024 bytes as compact JSON. A user's body is at most the key
  `scope`, `null` or such a scope. The parser then returns the rules in
  order with trimmed values, and otherwise refuses the body as `Invalid`.
  The shared oracle is `fuzz/oracles/patron_scope_request.rs`, replayed
  from `bookclerk-library`.
- **`chapter_request`**: an input's first byte picks the route (even:
  edit, odd: pin) and the rest is the body, read as an untyped JSON value
  with no key written twice anywhere. An edit is accepted exactly when it
  is one object holding only `chapters`, an array of at most 2,000
  objects each with a string `title`, a whole-number `start_ms`,
  optionally a 32-bit `depth` and no other key, where every title is 1
  to 512 bytes with no control character and no leading or trailing
  white space, every start is at most sixty days of milliseconds and no
  earlier than the one before, and the first depth is 0 and each later
  one at most one deeper than the one before and at most 7; the parser
  then returns exactly those chapters. A pin is accepted exactly when it
  is one object with a `source_kind` naming one of the seven kinds and
  optionally a `source_id`, a string (or `null`, read as empty) of at
  most 256 bytes with no control character. Anything else is refused as
  `Invalid`. The routes refuse a body over the parsers' length limits
  (`413`) and one not sent as JSON (`415`) before parsing it. The shared
  oracle is `fuzz/oracles/chapter_request.rs`, replayed from
  `bookclerk-library`.
- **`work_split_request`**: reads the body as an untyped JSON value. It
  is accepted exactly when it is one object with no repeated keys and
  exactly the key `expression_ids`, an array of strings each 1 to 64 bytes
  long, with 1 to 12 distinct values (a repeated id counts once). The
  parser then returns those ids sorted and distinct, and otherwise refuses
  it as `Invalid`. The shared oracle is `fuzz/oracles/work_split_request.rs`,
  replayed from `bookclerk-library`.
- **`playback_request`**: an input's first byte picks the part. For `s`
  (sync) and `c` (close) the rest is a body, read as an untyped JSON
  value: it is accepted exactly when it is at most 1,024 bytes and one
  object with no repeated keys, a `position_ms`, optionally a
  `listened_ms` and a `duration_ms` (which may be `null`) and no other
  key, each a whole number from 0 to sixty days of milliseconds. The
  parser then returns those numbers unchanged, and otherwise refuses the
  body as `Invalid`. For `t` the rest is a stream path's session id and
  track index, checked byte by byte: accepted exactly when the id is a
  lowercase hyphenated UUID and the index a number from 0 to 511 with no
  sign or leading zero. For `o` (open a session), `p` (set progress),
  `b` (add a bookmark) and `e` (change one) the rest is that route's
  body, at most 4,096 bytes and one object with no repeated or unknown
  keys. A session body has an `edition_id` of 1 to 128 bytes, a `player`
  that is absent, `web` or `desktop`, and an optional `player_name`,
  returned with control characters dropped, trimmed and cut to 64 bytes
  on a character boundary. A progress body's two lengths and its
  `is_finished` flag are each absent, `null` or in range. A bookmark
  body's title, trimmed, is at most 200 bytes with no control character.
  For `q` the rest is a progress page cursor, decoded with the oracle's
  own Base64 decoder: accepted exactly when it is at most 256 bytes of
  canonical unpadded URL-safe Base64 for a change time, a `|` and an
  edition id of 1 to 128 bytes, and an accepted cursor writes back to
  the same token.
  The routes refuse a body over the parsers' length limits (`413`)
  before reading it as the same JSON type, so they accept nothing the
  parsers refuse.
  The shared oracle is `fuzz/oracles/playback_request.rs`, replayed from
  `bookclerk-library`.
- **`player_request`**: an input's first byte picks the part. A login
  body is accepted only when it is one object with string `username` and
  `password`, and comes back with the username trimmed, both at most 256
  bytes and the password kept out of `Debug`. A card token is accepted
  exactly when, without surrounding whitespace, it is 43 URL-safe Base64
  letters, and comes back without that whitespace. Accepted list and detail
  queries are at most 4,096 bytes, with a page size of at most 1,000 and a
  search term of at most 256 bytes with no control character. An author,
  series or narrator id writes back from its key to the same id, and a
  file `ino` is accepted exactly when it is a canonical decimal below 512.
  Every length a sync, progress change, batch or bookmark yields is at
  most sixty days of milliseconds, a bookmark title at most 200 bytes, and
  a batch at most 100 entries of entity ids. The browser sign-in's start
  and way back name only the apps the library returns to, the start with
  a 43-byte S256 challenge, and a typed player password normalizes to 20
  symbols of its alphabet that format back to the same password. The
  shared oracle is `fuzz/oracles/player_request.rs`, replayed from
  `bookclerk-player-api`.
- **`player_socket`**: checks each frame from its leading characters
  rather than through the parser: a frame over 16 KiB is refused as too
  long, `1` alone is a close, `2…` a ping, `3…` a pong, `5` or `6` alone
  nothing, and only `40`, `41` and `42` are a connect, a disconnect and an
  event. An `auth` event carries its first argument when that is a string
  (else an empty token), and any other event's name is at most 64 bytes.
  The shared oracle is `fuzz/oracles/player_socket.rs`, replayed from
  `bookclerk-player-api`.
- **`work_tags_request`**: reads the body as an untyped JSON value. It is
  accepted exactly when it is one object with no repeated keys and exactly
  the key `tags`, an array of strings each at most 256 bytes once trimmed,
  with at most 32 distinct non-blank values ignoring case. The parser then
  returns those values trimmed, in the order sent with the first spelling
  kept, and otherwise refuses it as `Invalid`. The shared oracle is
  `fuzz/oracles/work_tags_request.rs`, replayed from `bookclerk-library`.
- **`collections_request`**: reads the body as an untyped JSON value. It
  is accepted exactly when it is one object with no repeated keys at any
  level and exactly the key `collections`, an array of at most 32 objects
  with exactly `name` and `prefixes`. Each name, trimmed, is 1 to 64 bytes
  with no NUL and no two match ignoring case; each collection has 1 to 8
  prefixes, each trimmed, non-empty, not starting with `/`, with no NUL,
  and at most 256 bytes once a closing `/` is added; and the result comes
  to at most 8 KiB as compact JSON. The parser then returns the trimmed
  names and normalized prefixes (repeats dropped) in the order sent, and
  otherwise refuses it as `Invalid`. The shared oracle is
  `fuzz/oracles/collections_request.rs`, replayed from `bookclerk-library`.
- **`sharing_request`**: reads the body as an untyped JSON value. It is
  accepted exactly when it is one object with no repeated keys and no keys
  besides `library_id`, `share_books`, `include_branches`,
  `list_members_books`, `work_for_members`, `keep_member_copies` and
  `keep_copies`, with a string `library_id` and booleans for `share_books`
  and `include_branches`, and each of the other four absent, `null` or a
  boolean. The parser then returns the trimmed id and those values, with
  an absent or `null` setting left unset (kept as stored) rather than read
  as `false`, and otherwise refuses it as `Invalid`. The shared oracle is
  `fuzz/oracles/sharing_request.rs`, replayed from `bookclerk-library`.
- **`connections_request`**: feeds each input to both parsers and reads it
  as an untyped JSON value. An add body is accepted exactly when it is one
  object with no repeated keys anywhere and only `library_id` (a string)
  and `accounts`, an array of 1 to 64 objects that each hold exactly a
  string `plugin_key` and a string `account_id`; the parser then returns
  the trimmed id and the accounts as sent. A disconnect body is accepted
  exactly when it is one object with no repeated keys, string
  `plugin_key` and `account_id`, and `everywhere` absent (read as `false`)
  or a boolean, and nothing else. Anything else is refused as `Invalid`.
  The shared oracle is `fuzz/oracles/connections_request.rs`, replayed
  from `bookclerk-library`.
- **`pace_request`**: reads the body as an untyped JSON value. It is
  accepted exactly when it is one object with no repeated keys and no keys
  besides `mode`, `downloads_per_day`, `min_gap_seconds` and
  `clear_cooldown`; `mode` is `default`, `custom` or `unlimited`;
  `clear_cooldown` is absent, `null` or a boolean; and each number is
  absent, `null` or a whole number in range (1 to 10000 downloads, 0 to
  86400 seconds). Only `custom` may carry a number, and it needs at least
  one. Anything else is refused as `Invalid`. The shared oracle is
  `fuzz/oracles/pace_request.rs`, replayed from `bookclerk-library`.
- **`download_resume`**: the input is a flags byte (the length is already
  known; the answer sent `Content-Length`; it sent `Content-Range`), the
  resume offset, the known length and the `Content-Length` (eight bytes
  each, big endian), the status (two bytes) and then the `Content-Range`
  value as sent. The parser answers exactly what the oracle reads by
  splitting the value as UTF-8 text and folding digits into a 128-bit
  integer; and the step equals the one the oracle works out from the
  rules: a `206` is appended only when its range starts at a non-zero
  offset, its length agrees with a known one and its `Content-Length`
  with its span, and the step names the range's end so the body is held
  to it; a `200` replaces the partial; a `416` finishes it only at
  `bytes */<offset>`; `408`, `429` and `5xx` retry; any other status fails.
  Seeds named after a step (`append-*`, `replace-*`, `complete-*`,
  `startover-*`, `retry-*`, `fail-*`) must take it. The shared oracle is
  `fuzz/oracles/download_resume.rs`, replayed from `bookclerk-plugin-sdk`.
- **`throttle_reason`**: restates the throttle words byte by byte. Refusal
  text is a throttle exactly when it contains `throttl`, `rate limit`,
  `rate-limit`, `ratelimit`, `too many requests` or `429`, ignoring ASCII
  case;
  changing the text's case never changes the answer, adding "Too Many
  Requests" always makes it a throttle, and adding other limit wording
  (a device or download limit, "Too many devices registered") never
  makes a plain refusal one. The
  shared oracle is `fuzz/oracles/throttle_reason.rs`, replayed from
  `bookclerk-storefront`.
- **`window_policy`**: restates the policy from the bytes. A request is
  refused as foreign exactly when its `Origin` is not byte for byte one of
  the two app origins, or when it has no `Origin`, is a write, and its
  `Referer` is not a URL on an app origin; otherwise it is refused exactly
  when its path is the node API or the live socket, by whole segments. The
  headers the router sees never hold the page's cookies, credentials,
  `Referer` or forwarding headers, always hold one `Host: localhost` and
  one `Origin: http://localhost`, carry `Bearer <token>` only when a token
  was given and the window's own `Cookie` text only when cookies were
  given, and keep every other header unchanged. Navigation allows app
  pages always and, only while a join is open, `https` and loopback `http`
  sign-in pages, with the return to the join callback kept on its path. The
  `live` command answers only the webview labelled `main` on an app page.
  The shared oracle is `fuzz/oracles/window_policy.rs`, replayed from
  `bookclerk-window-policy`.

## Boundaries outside the Rust workspace

These boundaries follow the ADR's rule for non-Rust tooling (decision 6).
Each one has a replay test and seeded mutation fuzzing, checked against
an independent oracle, and most replay a seed corpus. Python scripts run
them on every pull request; the Workers run them in `npm test`, inside the
Workers runtime (Vitest with `@cloudflare/vitest-plugin`), which reads each
corpus through Vite rather than from disk. The collector's summary and
Triage now fuzz tests run in Node instead, since their oracles are Python
subprocesses.

### Diagnostics scripts (Python)

The tests live in `scripts/tests/`, and each corpus beside them.

- **Holding issue editor**
  (`tools/diagnostics-collector/scripts/holding_issue.py`). It appends
  report IDs to the hidden report block in the body of the GitHub issue
  that holds untriaged reports, a body anyone with triage rights can edit.
  - Test and corpus: `test_holding_issue.py`, `holding_issue_corpus/`.
  - Oracle: an independent reading of the body, using the dashboard's
    block rule. Only a body whose last block's ID lines end on its `-->`
    line is edited. The new IDs follow the listed ones inside it, nothing
    else in the body changes, the list and body stay within their caps, and
    a second append changes nothing.
- **Triage plan validator**
  (`tools/diagnostics-collector/scripts/validate_plan.py`). It decides what
  model output reaches public issues.
  - Test and corpus: `test_diagnostics_plan.py`,
    `diagnostics_plan_corpus/`.
  - Oracle: no links, mentions, cross-references, raw HTML, comments, or
    forged Report IDs or report blocks. Only batch report IDs, listed bare
    in the one report block that ends the body, and at most five issues.
    Attachments go only to the issues the collector offered, with only
    batch report UUIDs, each report under one issue and in no new issue,
    and at most twenty issues.
- **Regression issue planner**
  (`tools/diagnostics-collector/scripts/regression_issue.py`). It turns the
  `regression_of` entries of an ingest pull into public issues. Their
  versions and platforms come from reports anyone can submit, and their
  titles from issues anyone with triage rights can edit.
  - Test and corpus: `test_regression_issue.py`,
    `regression_issue_corpus/`.
  - Oracle: an independent re-derivation of the groups. One issue per
    closed issue and `major.minor` line, at most ten. Only the pull's
    report IDs, listed bare in the one report block that ends the body. A
    marker line names the validated issue number. No links, mentions, raw
    HTML or references in the title and prose beyond the closed issue and
    its fix pull request, both validated integers.
  - The dashboard's Report IDs parser (`dashboard/report-ids.ts`, below)
    reads that marker.
- **Summary comment renderer**
  (`tools/diagnostics-collector/scripts/summary_comment.py`). It turns the
  collector's `GET /issues/summaries` answer (counts, plus versions and
  platforms taken from reports anyone can submit) into the one comment the
  ingest run keeps on each issue.
  - Test and corpus: `test_summary_comment.py`, `summary_comment_corpus/`.
  - Oracle: an independent re-derivation. The first valid entry per issue,
    at most twenty, with the marker first. Only the answer's report IDs,
    each linked only to its own dashboard page. No links, mentions, raw HTML
    or references outside code spans, and no Report IDs heading.
  - The dashboard's port of the renderer
    (`tools/diagnostics-collector/dashboard/summary.ts`, behind the owner's
    "Update GitHub now" button) is held to the Python module as its oracle.
    `tools/diagnostics-collector/summary.fuzz.test.ts` renders the same seed
    corpus, and seeded text and value mutations of it, on both sides (the
    Python side through `scripts/tests/summary_comment_oracle.py`). It
    requires identical comments, fingerprints and origin checks.
- **Ingest release-tag reader**
  (`tools/diagnostics-collector/scripts/release_baseline.py`). It turns the
  GitHub `releases/latest` response into the tag the ingest job writes to
  `$GITHUB_OUTPUT` and passes to `/report`.
  - Test and corpus: `test_release_baseline.py`,
    `release_baseline_corpus/`.
  - Oracle: a refusal, an empty tag for a draft or prerelease, or exactly
    the body's own `tag_name` when it is 1–64 characters of
    `[A-Za-z0-9._-]`.

### Docs publishing (Python)

- **Previous dates reader** (`previous_dates` in
  `scripts/docs-publish.py`). It reads the docs repository's current
  `last-updated.json`, which carries the generated pages' dates forward
  from one publish to the next.
  - Test and corpus: `scripts/tests/test_docs_publish.py`,
    `scripts/tests/docs_publish_dates_corpus/`.
  - Oracle: an independent reading of the document's shape by exact types,
    of each date digit by digit against a days-in-month table, and of an
    optional `THH:MM:SSZ` time field by field.

### Image publishing (Python)

- **Release-tag reader** (`scripts/image_release_tags.py`). It turns a
  published release's `tag_name` into the registry tags
  `images-publish.yml` pushes.
  - Test and corpus: `scripts/tests/test_image_release_tags.py`,
    `scripts/tests/image_release_tags_corpus/`.
  - Oracle: a refusal, or exactly `<major>.<minor>.<patch>`,
    `<major>.<minor>`, `<major>` and `latest` when the tag is `v` and
    three dot-separated ASCII numbers of one to nine digits without
    leading zeros.

### Demo deploy (Python)

- **Registry and health readers** (`manifest_digest` and `live_version` in
  `scripts/demo_image.py`). `demo-deploy.yml` reads the registry's
  manifest for the published demo image and the live demo's
  `/_demo/health` answer. The digest becomes the image the public demo
  runs (after its attestation is verified), and the live commit decides
  whether a deploy happens at all.
  - Test and corpus: `scripts/tests/test_demo_image.py`,
    `scripts/tests/demo_image_corpus/` (manifests under `digest/`, health
    answers under `live/`).
  - Oracle: a digest only when the answer is a JSON object whose `digest`
    is a string of `sha256:` and 64 lowercase hex digits; a live commit
    only when `configured` is exactly `true` and `version` is 40 lowercase
    hex digits, each checked character by character.

### Tool versions bump (Python)

- **Releases listing and digest readers** (`select_release` and
  `parse_digest` in `scripts/tool_versions.py`). `tool-versions-bump.yml`
  reads a tool's GitHub releases listing and its image digest from the
  registry. The chosen version is written to `.tool-versions`, the
  Dockerfiles and the pull request title; the digest to the Dockerfiles'
  `FROM` lines.
  - Test and corpus: `scripts/tests/test_tool_versions.py`,
    `scripts/tests/tool_versions_corpus/` (listings named `<tool>__<case>`;
    digests under `digest/`).
  - Oracle: an independent reading of the listing by exact JSON types,
    each version digit by digit, and each `published_at` against a
    days-in-month table; the pick must be the newest non-draft,
    non-prerelease release past the cooldown and above the pin. A digest
    is accepted only as `sha256:` and 64 lowercase hex digits, checked
    character by character.

### Visual baselines (Python)

- **Lock, screenshot set, approval and role readers** (`parse_lock`,
  `png_size`, `validate_set`, `parse_approval`, `parse_command`,
  `parse_membership` and `parse_role` in `scripts/visual_baselines.py`).
  The `ui-visual` CI job reads a pull request's `ui/visual/baselines.lock`
  as a git ref, and the `Visual baselines` workflow commits the screenshots
  a pull request's run recorded and acts on edits of its review comment.
  - Test and corpus: `scripts/tests/test_visual_baselines.py`,
    `scripts/tests/visual_baselines_corpus/` (named `<kind>__<case>`).
  - Oracle: an independent byte-by-byte reading of the lock (`none` or 40
    lowercase hex digits), of the PNG signature and `IHDR` header with
    hand-decoded big-endian sizes, of each path piece by piece, and of
    each event by exact JSON types, accepting an edit only when ticking the
    one checkbox turns the old body into the new one, and a reply only when
    it is exactly `@bookclerk approve-visuals` in ASCII, case and
    surrounding whitespace aside (look-alike letters are refused).

### CodeQL language chooser (Python)

- **Changed-path reader** (`parse_paths` and `rust_reason` in
  `scripts/codeql_languages.py`). `codeql.yml` reads the pull request's
  changed file names, which its author chose, and decides whether any is a
  Rust input. A pull request with none reuses `main`'s Rust results (see
  [CodeQL](/docs/contributing/ci/index.md#codeql)). The scan for embedded files (`scan_repo`)
  runs only when no changed path is a Rust input, so every `.rs` file it
  reads is `main`'s code, not the author's; it is unit-tested against the
  repository's own includes.
  - Test and corpus: `scripts/tests/test_codeql_languages.py`,
    `scripts/tests/codeql_languages_corpus/` (files named `rust__<case>`
    or `norust__<case>`).
  - Oracle: Rust is analyzed exactly when some NUL-separated name is not
    UTF-8, ends in `.rs`, `.capnp`, `.proto`, `.cc` or `.h`, is named `Cargo.toml`, `Cargo.lock`
    or `rust-toolchain.toml`, sits under a `.cargo/` directory, or is the
    workflow or one of the two scripts, checked with string operations
    rather than glob patterns.

- **Rust result reuse** (`candidate_runs`, `rust_job_succeeded` and
  `sarif_problem` in `scripts/codeql_reuse.py`). It reads GitHub API
  responses and SARIF that `main`'s own runs kept, not pull request
  content, so it isn't an untrusted boundary. Its output decides what a
  pull request uploads, though, so it is fuzzed the same way.
  - Test and corpus: `scripts/tests/test_codeql_reuse.py`,
    `scripts/tests/codeql_reuse_corpus/` (files named `runs__<case>`,
    `jobs__<case>` or `sarif__<case>`), replayed and mutated both as
    bytes and as JSON values.
  - Oracle: explicit walks with exact type checks. A run qualifies only
    when its id is an integer and it is a completed run on `main` for the
    base commit from a push, the schedule or a manual run. A run is
    reused only when it has exactly one successful `Analyze (rust)` job.
    A SARIF file is accepted only when it is version 2.1.0, every run is
    from CodeQL, and every run carries the id `/language:rust`.

- **Missing-runner recovery** (`queued_pr`, `pr_run_attempt`,
  `run_lineage`, `newer_run`, `stranded_jobs`, `not_acquired`, `pr_head`,
  `enqueues_since_head`, `first_enqueue_on_head`, `gate_run`,
  `stranded_job`, `gate_passed` and `previous_queue_run` in
  `scripts/merge_queue_requeue.py`). It reads GitHub API responses about
  a failed merge-group or pull request run, not pull request content, so
  it isn't an untrusted boundary. Its output decides whether a pull
  request goes back in the queue, a run is re-run, or `CI Gate` passes
  without the macOS job, though, so it is fuzzed the same way.
  - Test and corpus: `scripts/tests/test_merge_queue_requeue.py`,
    `scripts/tests/merge_queue_requeue_corpus/` (files named
    `run__<case>`, `runs__<case>`, `jobs__<case>`, `annotations__<case>`,
    `pr__<case>` or `timeline__<case>`, trimmed from the run that removed #604 from the
    queue), replayed and mutated both as bytes and as JSON values.
  - Oracle: explicit walks with exact type checks. A run counts only when
    it is a failed or cancelled `merge_group` run of `ci.yml` in this
    repository on a `gh-readonly-queue/main/pr-<n>-<40 hex>` branch. A
    pull request run's attempt counts only when the run is a failed
    `pull_request` run of `ci.yml` whose base repository is this one and
    whose `run_attempt` is an integer of at least 1. A run's lineage
    needs a non-empty head repository and branch and a `run_number` of at
    least 1; a run listing supersedes it only when every entry is an
    object with an integer `run_number` and one from the same head
    repository has a larger number. Jobs
    qualify only when every job that didn't succeed or skip is a follower
    job or was cancelled with no runner and no steps. The annotation check
    needs a `failure` annotation naming the not-acquired runner. A pull
    request qualifies only when it is open, `draft` is `false`, auto-merge
    is unset and its head is a full commit id in this repository. Enqueues
    are counted after the last `committed` or `head_ref_force_pushed`
    event, and the first entry on the head is the first
    `added_to_merge_queue` event after it, which needs a
    `YYYY-MM-DDTHH:MM:SSZ` `created_at`. For `CI Gate`, a run counts only when it is a `pull_request` or
    `merge_group` run of `ci.yml` in this repository with a non-empty head
    branch; a job is stranded only when exactly one job has its name (or
    `<caller> / <name>`) and it completed `cancelled` with no runner and
    no steps; the gate passed only when a job named `CI Gate` (or
    `<caller> / CI Gate`) succeeded; and a pull request's previous merge
    group is the queue-branch run for that pull request with the largest
    `run_number` below the current one and a `created_at` no earlier than
    that first entry, across listing pages whose every entry has an
    integer `id` and `run_number`, a string head branch and a timestamp
    `created_at`.

- **Pull request lanes** (`active_runs`, `queue_holds_runners` and `lane_loads` in
  `scripts/ci_lanes.py`). It reads GitHub API responses about this
  repository's active CI runs and their jobs, so it isn't an untrusted
  boundary. Its output decides which lane each pull request job waits in
  and whether lanes are lent (see [Pull request lanes](/docs/contributing/ci/index.md#pull-request-lanes)),
  though, so it is fuzzed the same way.
  - Test and corpus: `scripts/tests/test_ci_lanes.py`,
    `scripts/tests/ci_lanes_corpus/` (files named `runs__<case>` or
    `jobs__<case>`, trimmed from the runs waiting on 11 November 2026),
    replayed and mutated both as bytes and as JSON values.
  - Oracle: explicit walks with exact type checks. A listing is unreadable
    when any run lacks an integer `id` or a string `event` or `status`, or
    any job lacks a string `name` or `status`. A run counts only when it is
    a `ci.yml` run in this repository with a queued, in-progress, pending,
    waiting or requested status; a `merge_group` one is listed for its jobs.
    A merge group holds the queue when its job list is empty or any job
    with one of those statuses doesn't have "report only" in its name.
    A job counts toward a lane only when its status is one of those and its
    name ends in ` · lane ` and a lane number below 54 with no leading
    zero, split off with `rpartition` and checked digit by digit.

- **Mutation testing start commit** (`choose` in
  `scripts/mutation_base.py`). The nightly mutation workflows read the
  commit of their last successful run from the GitHub API and diff `main`
  against it (see [Mutation testing](/docs/contributing/ci/index.md#mutation-testing)). The answer
  is checked before git sees it.
  - Test and corpus: `scripts/tests/test_mutation_base.py`,
    `scripts/tests/mutation_base_corpus/` (files named `sha__<case>`),
    replayed and mutated as bytes.
  - Oracle: a candidate is accepted only when, with surrounding whitespace
    removed, it is exactly 40 characters, each a lowercase hex digit,
    checked character by character rather than with a pattern. git is
    asked about nothing else, and the first such candidate git confirms
    wins.

- **ClusterFuzzLite artifact lookup** (`newest_artifact` in
  `scripts/cflite_artifacts.py`). Every fuzzing run finds each target's
  corpus and the coverage report with one listing of the artifacts by
  name (see [Artifact lookups](#artifact-lookups)). The listing names
  artifacts that `main`'s scheduled runs uploaded, not pull request
  content, so it isn't an untrusted boundary. Its answer decides where the
  job's token is sent, though, so it is fuzzed the same way.
  - Test and corpus: `scripts/tests/test_cflite_artifacts.py`,
    `scripts/tests/cflite_artifacts_corpus/` (files named
    `artifacts__<case>`, trimmed from a real listing), replayed and
    mutated both as bytes and as JSON values.
  - Oracle: an explicit walk with exact type checks. The first entry
    wins whose `id` is a positive integer, whose `name` is the one asked
    for, whose `expired` is `false` and whose `archive_download_url` is
    exactly `<listing>/<id>/zip` on this repository's API.

### CLA check (Python)

- **CLA checker** (`scripts/cla_check.py`). It reads the workflow event
  (including the head a `workflow_run` names and the check a `check_run`
  re-run names), the pull request, its commit
  and comment pages, the co-author query answer, the lists of pull requests
  that contain the head commit or come from the head branch, the
  signature file, the git objects it creates when the first signature
  starts the signature branch, the reactions it adds to signing
  comments, the check runs it creates, a commit's combined status, and
  the rules that apply to that branch,
  and decides who still has to sign. Logins, comment bodies and commit
  metadata in them are chosen by contributors.
  - Test and corpus: `scripts/tests/test_cla_check.py`,
    `scripts/tests/cla_check_corpus/` (files named `<kind>__<case>`).
  - Oracle: an independent field-by-field reading of each document, which
    refuses any account whose login does not fit its type (`[bot]` logins
    only for bot accounts). For fuzzed commit pages, the unsigned accounts
    are exactly the pull request author and linked commit authors and
    co-authors, minus the allowlisted bots, the assistant accounts and the
    signed ids. The comment mentions only them and links only to the CLA.

### Maintainer review (Python)

- **Maintainer review check** (`scripts/maintainer_review.py`). It reads
  the workflow event (the head a `workflow_run` names, a merge group's
  head, the check a `check_run` re-run names), collaborator permission
  answers, and the pull request's review and changed-file pages, and
  decides whether an outside pull request may merge. Logins, branch names
  and file paths in them are chosen by contributors. It shares the CLA
  checker's JSON readers and pull request parsers.
  - Test and corpus: `scripts/tests/test_maintainer_review.py`,
    `scripts/tests/maintainer_review_corpus/` (files named
    `<kind>__<case>`).
  - Oracle: an independent field-by-field reading of each document, which
    refuses absolute paths, `..` segments and accounts whose login does not
    fit their type. For fuzzed file pages, the flagged paths are exactly
    those an independent reading of the sensitive prefixes, names and
    missing diffs selects, and each listed path stays inside one code span
    in the summary.

### Signed commits (Python)

- **Signed commits check** (`scripts/signed_commits.py`). It reads the
  workflow event (the head a `workflow_run` names, a merge group's head,
  the check a `check_run` re-run names), the pull request with its base
  and default branch, and its commit pages with GitHub's verification of
  each commit, and writes a comment from them. Branch names, logins, titles
  and commit messages in them are chosen by contributors. It shares the CLA checker's JSON readers and comment
  page parser and the maintainer review check's event and pull request
  readers.
  - Test and corpus: `scripts/tests/test_signed_commits.py`,
    `scripts/tests/signed_commits_corpus/` (files named `<kind>__<case>`).
  - Oracle: an independent field-by-field reading of each document, which
    refuses a `verified` that isn't a boolean, a `reason` that isn't
    lowercase letters and underscores, and a default branch name the
    re-sign command could not quote safely. For fuzzed commit pages, the comment
    lists exactly the commits the independent reading finds unverified,
    each table row keeps its two cells, and the only link is GitHub's
    signing guide.

### Coverage gate (Python)

- **Coverage report and diff readers** (`parse_lcov` and `parse_diff` in
  `scripts/coverage_gate.py`). CI Gate reads the LCOV reports and the
  change's hunk headers that the pull request's own run uploaded, so a
  pull request chooses their bytes.
  - Test and corpus: `scripts/tests/test_coverage_gate.py`,
    `scripts/tests/coverage_gate_corpus/` (files named `<kind>__<case>`).
  - Oracle: an independent reading of each report record and hunk header
    with full-line patterns, and of each `SF:` path by walking its
    segments. Every path the module keeps is relative to the repository
    and never climbs out of it, and every hit count is a non-negative
    integer.
  - The Codecov upload sends only what this parser accepted:
    `--export` writes each parsed report back out, and a test checks that
    the written report reads back the same.
- **JUnit test results reader** (`parse_junit` in `scripts/coverage_gate.py`).
  The Codecov upload reads the JUnit reports the pull request's own run
  uploaded, so a pull request chooses their bytes.
  - Test and corpus: the same test file and corpus (`junit__<case>`).
  - Oracle: the boundary's contract, since the standard library has no
    second XML parser. A report with a document type declaration reads as
    empty. Every kept name is one line of safe characters within its
    limit. Durations are finite and in range. Failure text appears only on
    a failed or errored case. The report the export writes reads back to
    the same test cases.
- **Bundle file selection** (`select_bundle_files` and `export_bundles` in
  `scripts/coverage_gate.py`). The Codecov upload reads the built bundles
  the pull request's own run uploaded, so a pull request chooses their file
  names and sizes.
  - Test and corpus: the same test file and corpus (`bundle__<case>`, one
    `<size>` tab `<path>` line per file).
  - Oracle: a second selection that splits each path into segments instead
    of matching one pattern. Kept paths never start with `/`, climb with
    `..` or hold a backslash, and the kept files stay within the count and
    size limits. Symbolic and hard links are never followed or copied.

### Diagnostics collector Worker

The tests and corpora live in `tools/diagnostics-collector/`.

- **`/triage` admission** (`admitBatch` in `triage.ts`). It parses the
  report-derived batch and prices it against the daily neuron budget.
  - Test and corpus: `triage-admit.fuzz.test.ts`, `corpus/triage_admit/`.
  - Oracle: a refusal has a cause. An admitted prompt is the re-serialized
    batch, after the Worker's own open-issue list when there is one. The
    batch fits the size cap and the prompt fits the context window, and the
    reservation covers the call's worst case.
- **Triage now reply reader** (`proposalFor` in `dashboard/triage-now.ts`).
  It reads the model's reply about one report into the issue or
  attachment a member may file from the report page.
  - Test and corpus: `triage-now.fuzz.test.ts`, which replays and mutates
    the plan validator's corpus (`scripts/tests/diagnostics_plan_corpus/`)
    and builds plans from hostile values; `triage-now.test.ts` covers the
    Workers runtime's reading of numbers.
  - Oracle: the ingest run's plan validator
    (`tools/diagnostics-collector/scripts/validate_plan.py`, through
    `scripts/tests/diagnostics_plan_oracle.py`) with that report as its
    whole batch. Both must propose the same attachment, or the same issue
    title, labels and filed body, or nothing. The reader may refuse more:
    replies over its length cap, JSON nested deeper than its cap, and
    `NaN` or `Infinity`, which Python's JSON reader accepts.
- **Ingest cursor body** (`parseCursor` in `ingest-cursor.ts`). It is the
  body `POST /report/cursor` stores, and decides where the next ingest run
  starts.
  - Test and corpus: `ingest-cursor.fuzz.test.ts`,
    `corpus/ingest_cursor/`.
  - Oracle: a cursor exactly when the body is a JSON object whose `since`
    is a safe non-negative integer, and whose `after` (absent or null
    meaning empty) is a string of at most 1,024 characters with no control
    characters.
- **B2 error-code reader** (`b2ErrorCode` in `worker.ts`). It picks the
  `code` out of a B2 error body for logs and authenticated responses.
  - Test and corpus: `b2-error.fuzz.test.ts`, `corpus/b2_error/`.
  - Oracle: nothing, or exactly the body's own `code` when it is a 1–40
    character lowercase identifier.
- **Usage check-in body** (`parseCheckin` in `checkin.ts`). It is the body
  anyone can send to `POST /checkin`, and decides what a check-in row
  stores and which install ID is hashed into the install key.
  - Test and corpus: `checkin.fuzz.test.ts`, `corpus/checkin/`.
  - Oracle: a check-in exactly when the body is at most 1,024 characters
    of JSON naming an object with exactly the five fields, a lowercase
    version-4 UUID checked by position, and version, platform and kind
    tokens checked character by character.
- **Diagnostics report body** (`parseSubmit` in `submit.ts`). It is the
  body anyone can send to `POST /submit`, read under the 256 KiB cap while
  it streams (`readCapped`), and decides what report is stored in B2.
  - Test and corpus: `submit.fuzz.test.ts`, `corpus/submit/`.
  - Oracle: a report exactly when the body is JSON naming an object whose
    trigger (1–64 characters), version (at most 64, not all whitespace)
    and OS (at most 64) are strings, whose `archived_at_unix_ms` is absent
    or a number, and whose `events` is an array of at most 500 objects
    with no string `message`, `level` or `target` over 8,000, 32 or 256
    characters. An admitted report equals the parsed body.
- **Report lookup body** (`parseLookupInput` in `report-access.ts`). It
  is the body anyone can post to `/lookup` and `/lookup/delete`, as JSON
  or a form, and names the report a code is checked against and whether a
  form confirmed a deletion.
  - Test and corpus: `report-access.fuzz.test.ts`, `corpus/lookup_input/`
    (each seed's first line is the `Content-Type`).
  - Oracle: a request exactly when the body is at most 1,024 characters
    and is either a JSON object with exactly the string fields `report_id`
    and `access_code`, or a form (decoded by the test's own reader) with
    those two once each and at most `confirm=yes` besides; the ID, trimmed
    and lowercased, is a version-4 UUID checked by position, and the code,
    normalized by regular expressions, is 16 Crockford base32 characters.
- **B2 version listing** (`decodeVersionPage` in `dashboard/storage.ts`).
  It reads B2's `b2_list_file_versions` answer for one object, and its
  result is every file version a deletion removes.
  - Test and corpus: `report-access.fuzz.test.ts`, `corpus/b2_versions/`.
  - Oracle: exactly the string `fileId`s of the entries whose `fileName`
    is the object's key, in order, and more to read exactly when
    `nextFileName` is that key and `nextFileId` a string.
- **Hosted demo run event** (`parseDemoRunEvent` in `demo-runs.ts`). It is
  the value the demo Worker passes to the collector's `DemoRuns`
  entrypoint over its service binding (no public route), and decides what
  a `demo_runs` row stores.
  - Test and corpus: `demo-runs.fuzz.test.ts`, `corpus/demo_run/`.
  - Oracle: an event exactly when the value is an object with exactly its
    kind's keys, a lowercase version-4 UUID checked group by group, a
    version of `[0-9A-Za-z._+-]` checked character by character, whole
    times from 2020 to 2100 with the hard stop after the start and at most
    six hours later, a whole startup of 0 to 600 seconds, a stop between
    the start and a day after the hard stop, and one of the demo's six end
    reasons.

### Member dashboard

The member dashboard's readers of untrusted text share one test,
`tools/diagnostics-collector/dashboard-input.fuzz.test.ts`. Each reader
below names the corpus it replays, under `tools/diagnostics-collector/`,
and the oracle its results are checked against.

In `dashboard/report-ids.ts`, `dashboard/signature.ts`,
`dashboard/pages.ts` and `dashboard/session.ts`:

- **Report IDs parser** (`parseIssueReportIds`) decides which reports an
  issue claims. Corpus `corpus/report_ids/`. Oracle: IDs re-derived by a
  separate walk, all UUIDs present in the body, capped.
- **Stored-report summary** (`summarizeReport`) writes every report's index
  row. Corpus `corpus/signature/`. Oracle: level counts recounted, a
  signature exactly when an error or warning exists, bounded control-free
  fields, the slowest `latency_ms` recomputed, an install key only when the
  stored one is 64 lowercase hex characters, and a route only with a
  signature.
- **Event log** (`eventLog`) renders a report page's stored events. Corpus
  `corpus/signature/` (shared with the signature reader). Oracle: one row
  per event up to 500, level counts that add up to the rows, no event text
  left as markup, and no throw.
- **Session check** (`sessionToken` and `memberFromRow`) decides whether a
  request is signed in, and as whom. Corpus `corpus/session/`. Oracle: a
  session token found exactly when a separate cookie walk finds a
  well-formed one; a member only for a live row with a valid id and login;
  admin only when the row says so.

In `dashboard/auth.ts`:

- **Sign-in callback check** (`parseCallback`) decides, from the callback
  query and cookies, whether a code is traded with GitHub and which page
  the member lands on. Corpus `corpus/oauth_callback/`. Oracle: accepted
  exactly when a separate cookie walk finds a state that matches the query
  and a well-formed code and verifier. It returns those values, and a
  return page that the URL parser resolves on the same origin to a
  dashboard page.
- **Return-page check** (`safeNext`) turns a `next` query parameter or
  cookie part into a redirect target. Corpus `corpus/next_path/`. Oracle: a
  return page kept only when it is such a page, and never refused when it
  is one.

In `dashboard/github.ts`:

- **Membership decision** (`membershipDecision`) decides, from GitHub's
  membership answer, whether sign-in grants member or owner access. Corpus
  `corpus/membership/`. Oracle: granted only for an active membership with
  the same user id, or a 404 for the owner itself; admin only when GitHub
  says so; an error for any other failed status.
- **Pull request decoder** (`decodePullRequests`) decides, from GitHub's
  GraphQL answer, whether the sync drops an issue or replaces its pull
  request links. Corpus `corpus/pull_requests/`. Oracle: decoded to exactly
  the well-formed pull requests in this repository; the label check fails
  only on a complete label list without `diagnostics`; an error for GraphQL
  errors or a missing repository.
- **Issue listing decoder** (`decodeIssuePage`) moves the sync cursor and
  feeds `storeIssue`. Corpus `corpus/issue_page/`. Oracle: decoded to the
  numbered non-PR entries with string fields, full by raw count, with the
  newest parseable update.
- **Sign-in and token decoders** (`decodeInstallationId`,
  `decodeInstallationToken`, `decodeAccessToken`, `oauthErrorCode`,
  `decodeUser`). Corpus `corpus/github_auth/`. Oracle: tokens, ids and users
  accepted only when well-formed; an OAuth error code kept only when it is
  a short lowercase identifier.
- **Issue notice** (`parseIssueNotify`) and **single-issue decoder**
  (`decodeIssue`), from the ingest Action, decide which issue is re-read
  and whether it stays linked. Corpora `corpus/issue_notify/` and
  `corpus/issue/`. Oracle: a notice accepted only as an object whose
  `issue` is an integer from 1 to 10^9; a single issue decoded only when it
  is a numbered non-PR issue, labeled exactly when a label is
  `diagnostics`.
- **Summary receipt** (`parseSummaryDone`), from the ingest Action, decides
  which issue stops being handed out for a summary comment. Corpus
  `corpus/summary_done/`. Oracle: a separate walk over the parsed value,
  with the fingerprint checked character by character.
- **Attach body** (`parseAttachRequest`), from the ingest Action, decides
  which reports the ledger links to which open issues as triage's. Corpus
  `corpus/triage_attach/`. Oracle: accepted only as a `links` list of at
  most twenty objects, each a distinct issue number from 1 to 10^9 with a
  non-empty list of report UUIDs or collector object names, lowercased. A
  report is kept under the first issue naming it, at most five hundred in
  all, re-derived by a separate walk.
- **Issue comments decoder** (`decodeComments`) names the comment the
  owner's "Update GitHub now" button edits in place, or decides that one is
  posted. Corpus `corpus/issue_comments/`. Oracle: a hand walk of the
  first hundred entries that takes the first with a positive safe integer
  `id`, a `user` whose `type` is exactly `Bot`, and a `body` that begins
  with the marker.
- **Locked-issue reader** (`isLockedMessage`) decides whether GitHub's
  refusal of that write is final. Corpus `corpus/locked_message/`.
  Oracle: true only for an object whose `message` is a string of at most
  1000 characters containing "issue is locked" in any ASCII letter case,
  single-spaced, with no word character touching either end.

The same test also checks the release and fix-tracking readers against
these oracles:

- a merge commit kept only for a merged pull request with a 40-character
  lowercase hex oid;
- a `fixed-in:<version>` label read only as a well-formed
  `MAJOR.MINOR.PATCH`, with optional prerelease and build;
- label names for the close button read only from objects with a string
  `name` of at most 100 characters;
- releases decoded to the published non-draft entries with a plain tag
  name, oldest first;
- a compare answer read as containing only for `identical` or `behind`,
  and as not containing only for `ahead` or `diverged`;
- a default branch kept only when it is a plain git branch name, by rules
  written out one by one.

In `dashboard/links.ts` and `dashboard/storage.ts`:

- **Ledger correction form** (`parseLinkAction`) decides which report a
  member attaches to, detaches from or moves between which issues, and
  which issue is merged into which. Corpus `corpus/link_action/`. Oracle:
  accepted exactly when a separate walk over its pairs finds a known
  action, an issue number, a lowercase UUID where the action needs a
  report, and a different issue number where it needs a target.
- **B2 listing decoder** (`decodeListPage`) names the objects report
  viewing downloads, and where reindexing continues. Corpus
  `corpus/b2_list/`. Oracle: decoded to exactly the uploaded entries with a
  string name and id, without throwing.

In `dashboard/triage-forms.ts`, tested in
`tools/diagnostics-collector/triage-forms.fuzz.test.ts` against a form
body split and percent-decoded by hand:

- **Triage mark form** (`parseTriageMark`) decides which reports a member
  marks seen or noise, or puts back in the queue. Corpus
  `corpus/triage_form/`. Oracle: a known state and one to 40 distinct
  lowercase UUIDs.
- **Mute form** (`parseMuteAction`) decides which signature leaves the
  triage queue and the ingest pull, why, and until when. Corpus
  `corpus/mute_form/`. Oracle: a 16-hex signature, and for a mute a
  trimmed, control-free reason of 1 to 200 characters and exactly one end
  (1 to 365 days, or a release version).
- **Owner close form** (`parseCloseAction`) decides which issue an owner
  closes on GitHub and the fixed-in label it gets. Corpus
  `corpus/close_form/`. Oracle: an issue number, and a release version
  when closing as fixed.

### Website Worker

`tools/site/fuzz.test.ts` replays each corpus and runs seeded mutation
fuzzing in `npm test`.

- **`Accept-Encoding` parser** (`pickEncoding` in `tools/site/worker.ts`)
  picks the response's content coding. Corpus
  `tools/site/fuzz/accept_encoding/`. Oracle: RFC 9110 qvalues, `*` for
  unlisted codings, Brotli before gzip on a tie, nothing at `q=0`.
- **Page redirects** (`sitePageLocation` and `docsTarget` in
  `tools/site/worker.ts`) turn a request path into the page's one
  slash-free URL. Corpus `tools/site/fuzz/site_redirects/`. Oracle: the
  website moves exactly the slash and `.html` spellings of a listed page;
  a docs redirect stays under `/docs`, is slash-free, never repeats the
  request path and takes one hop, docs keys never leave the tree, and
  only a version's own `search-index.json` path names its search index.
- **Code-block highlighter** (`highlight` in `tools/site/highlight.ts`)
  colors fenced code from the docs repository. Corpus
  `tools/site/fuzz/highlight/`, fuzzed across its languages. Oracle: an
  independent reader confirms the output is only escaped text and `hl-`
  spans, and gives back the input exactly.
- **Mermaid diagrams** (`diagram` and `cleanSvg` in
  `tools/site/diagram.ts`) draw ```` ```mermaid ```` fences from the docs
  repository as inline SVG. Corpus `tools/site/fuzz/diagram/`, fuzzed on
  both the diagram sources and the SVG that `cleanSvg` rebuilds. Oracle:
  an independent reader confirms the output is one `<svg>` of allowed
  elements, with no script or style attributes, no class but `mono`, no
  reference outside the diagram, and ids carrying the page's prefix.
- **Web API layout** (`layoutOperations` in
  `tools/site/api-reference.ts`, through `renderDoc`) rearranges the
  generated Web API pages from the docs repository into operation
  sections, with one panel per example response (`layoutResponses`),
  one per example request language (`layoutRequests`) and property rows
  for the parameter, body and response lists (`layoutProperties`).
  Corpus `tools/site/fuzz/api_reference/`. Oracle: the HTML nests
  properly, every section is labelled by its own heading with one badge
  for a known method, every response panel has a unique id and a caption
  marking its status, every request panel has a unique id naming its
  language and holds one code block, every property row has its head and
  every fold its summary and list, and the page keeps the same text as it
  has without the layout.
- **Web API index layout** (`layoutIndex` and `indexRoutes` in
  `tools/site/api-reference.ts`, through `renderDoc`) lays out the
  generated Web API index as route group cards with a quick-start
  aside, and reads its routes for the sidebar. Corpus
  `tools/site/fuzz/api_index/`. Oracle: the HTML nests properly, every card
  and aside is labelled by its own heading, every badge names a known
  method, and the page keeps the same text as it has without the layout.
- **Last-updated reader** (`pageDate` and `datedPages` in
  `tools/site/last-updated.ts`) dates each docs page from the docs
  repository's `last-updated.json`, and lists every page for
  `/sitemap.xml`. Corpus `tools/site/fuzz/last_updated/`. Oracle: the
  document's shape read through property descriptors, the date digit by
  digit against a days-in-month table, an optional `THH:MM:SSZ` time field
  by field, and each sitemap key segment by segment. The date shown is only
  `Mon D, YYYY`, and its `<time>` element holds only the date's own
  characters.
- **Generated manifest reader** (`parseGenerated` and the lookups built
  on it in `tools/site/generated.ts`) reads the docs repository's
  `generated.json`, which says which pages the docs build generated, from
  what, and which reference each belongs to; the Worker uses it for the
  Web API layout, the source line, the sidebar lists and the sitemap
  page. Corpus `tools/site/fuzz/generated/`. Oracle: the document read
  through property descriptors by exact types, every folder, page and
  source path segment by segment, each page under its folder, and the
  lookups (a page's reference, whether it is generated, its source, the
  Web API's pages and a reference's modules) derived plainly from the
  oracle's reading.
- **IndexNow sitemap reader** (`readSitemap` in `tools/site/indexnow.ts`)
  reads the live site's sitemaps in the `indexnow` workflow, which then
  submits the URLs they list. Corpus `tools/site/fuzz/indexnow_sitemap/`.
  Oracle: a hand-written scanner for the entries the Worker writes, its own
  entity decoder, a URL check against the site's origin and the
  last-updated date oracle.
- **IndexNow snapshot reader** (`readSnapshot` in `tools/site/indexnow.ts`)
  reads the previous run's snapshot back from its artifact. Corpus
  `tools/site/fuzz/indexnow_snapshot/`. Oracle: the document read through
  property descriptors, each URL checked against the site's origin and each
  date by the last-updated date oracle.
- **IndexNow snapshot artifact lookup** (`previousSnapshotRun` in
  `tools/site/indexnow.ts`) reads GitHub's artifact listing in the
  `indexnow` workflow and picks the run whose snapshot the next run
  downloads. Corpus `tools/site/fuzz/indexnow_artifacts/`. Oracle: an
  explicit walk of own properties: the first entry wins that is named
  `indexnow-snapshot`, has `expired` exactly `false`, was uploaded on the
  default branch and whose run `id` is a positive safe integer.

### Hosted demo Worker

`tools/demo/test/inputs.fuzz.test.ts` replays the corpora under
`tools/demo/corpus/` and runs seeded mutation fuzzing in `npm test`. The
inputs live in `tools/demo/src/routes.ts`, `src/inputs.ts` and
`src/live.ts`.

- **Route check** (`classify`) decides whether a visitor's request may
  reach their container. Corpus `route/`. Oracle: a forwarded path decodes
  to clean segments and matches no refused operation, a write matches a
  listed one, and a sign-in start is always counted.
- **Visitor cookies** (`readSessionToken`, `cookiesForContainer`). Corpus
  `cookie/`. Oracle: the session cookie is found exactly when a separate
  walk finds a well-formed `__Host-demo`, and no `__Host-` or `__Secure-`
  cookie is forwarded.
- **Container `Set-Cookie` lines** (`rewriteSetCookie`,
  `portalSessionFrom`). Corpus `set_cookie/`. Oracle: a rewritten
  `Set-Cookie` keeps its name, has no `Domain`, ends in exactly one
  `Secure` and has no control characters. A portal session only when
  exactly one well-formed value is set.
- **Container JSON answers** (`decodeConnections`, `decodeClaimTicket`,
  `decodeInstances`, `decodeDiscoverReady`). Corpora `connections/`,
  `claim_ticket/`, `plugin_instances/`, `discover_status/`. Oracle:
  connections deduplicated, bounded and well-formed; a claim ticket only
  when well-formed; only wanted default plugin instances with well-formed
  ids, the first per plugin, on a well-formed node id, marked deployed
  only when that instance has a `present` row for that node; a shelves-ready flag
  only when `ready` is a boolean in an object.
- **Launch form** (`decodeLaunchForm`). Corpus `launch_form/`. Oracle: the
  token equals a separate form-urlencoded parse's first
  `cf-turnstile-response` when that is printable ASCII, and there is none
  from an oversized body or token.
- **Turnstile's verdict** (`siteverifyPassed`). Corpus `siteverify/`.
  Oracle: passed only for success on this host and action.
- **Live status socket** (`liveRequest`, `liveCommand`). Corpora
  `live_request/`, `live_message/`. Oracle: a socket only for a GET whose
  `Upgrade` is `websocket` in ASCII letters of either case, from this
  origin, with a session; a command only for exactly the text `sync`.
- **Cloudflare API answers at deploy time** (`decodeApiResponse`,
  `findWidget`, `widgetKeys` in `scripts/worker-secrets.ts`). Corpus
  `cf_api/`. Oracle: `result` only on a 2xx with `success: true`, otherwise
  only its integer error codes. The demo widget only with a printable site
  key and printable, deduplicated, bounded hostnames, and keys only when
  both are printable.

### Metadata provider guests

The `openlibrary` and `audnexus` guests parse upstream JSON inside the
jailed isolate. What reaches the host is the Cap'n Proto reply that
`abi_decode` and `abi_roundtrip` already cover, so these parsers guard the
records each guest returns. Each guest's `test/fuzz.test.ts` replays its
corpora under `fuzz/` and runs seeded mutation fuzzing, on the parsed JSON
tree and on its text, in `npm test` (the `workerd_guests` check).
`FUZZ_SEED` and `FUZZ_ITERATIONS` pick another run.

- **Open Library search results** (`recordsFromSearch` in
  `crates/bookclerk-plugins/optional/metadata-openlibrary/src/openlibrary.ts`),
  under a lookup and a title search. Corpus `fuzz/search_response/`.
  Oracle: a body is refused exactly when it is not an object or its `docs`
  is not a list. Records stay within the limit, each work and edition id
  appears in the body, ISBNs have the ISBN shape, the URL names the edition
  or else the work, and covers are Open Library cover URLs. Credits are
  distinct authors, and lists stay within their caps. Every string is
  non-empty, well-formed UTF-16 and at most `MAX_TEXT` long, and the
  mapping is deterministic.
- **Audnexus books** (`recordFromBook` in
  `crates/bookclerk-plugins/optional/metadata-audnexus/src/audnexus.ts`).
  Corpus `fuzz/book/`. Oracle: a record exactly when the body has a
  ten-character ASIN and a non-blank title, and the ASIN is the first
  identifier with the asked region. Credits are distinct per role and
  capped. At most two series entries. Dates are `YYYY-MM-DD`, covers are
  `https://`, lengths and ratings are in range, and the same string rules
  as Open Library apply.
- **Audnexus chapter layouts** (`chaptersFromBody`). Corpus
  `fuzz/chapters/`. Oracle: the chapters' starts and depths equal an
  explicit-stack pre-order walk of the body, down to `MAX_DEPTH` and up to
  `MAX_CHAPTERS`. `found` exactly when that walk finds any. Durations are
  positive safe integers.

### Cover fetcher guest

The `covers` guest decides which URLs it requests: the host's URLs and every
redirect `Location` an upstream server sends. It also passes header values
both ways: the host's validators out as request headers, and an upstream
server's caching headers back in its answer. Its `test/fuzz.test.ts` replays
`fuzz/url/`, `fuzz/location/` and `fuzz/header/` and runs seeded text mutations in
`npm test` (the `workerd_guests` check); `FUZZ_SEED` and `FUZZ_ITERATIONS`
pick another run.

- **Cover URL policy** (`checkUrl` in
  `crates/bookclerk-plugins/optional/covers/src/fetcher.ts`). Oracle,
  written from the policy and the WHATWG URL rules: accept exactly an
  `https` URL with the default port, no credentials, no control characters
  or spaces, at most 4096 code units, and a hostname whose labels are
  non-empty and whose last label is not a number (the URL parser's IPv4
  test) or a bracketed address. Accepted URLs are canonical and
  idempotent.
- **Redirect chains** (`fetchOne`). Mutated `Location` chains: every
  request is a policy URL, each hop is the previous `Location` resolved
  against the URL that sent it, no more than `MAX_REDIRECTS` are followed,
  and a body is stored only after a chain the policy allowed in full.
- **Header values** (`headerValueOk`, `checkParams` conditions and
  `passHeaders`). Oracle, written from the ABI's `maxCoverHeaderBytes` and
  the visible-ASCII part of RFC 9110's `field-value`: a value passes
  exactly when it is at most 1024 bytes of tab, space and `VCHAR`. A
  condition outside that is refused, and a response header outside it is
  dropped from the answer.

### Metadata file dialect guests

Two guests read sidecar files from storage the host does not control: the
shared `metadata_files` guest (`libation_json`) and the Audiobookshelf
plugin (`abs_metadata_json`, `abs_nfo`, `desc_txt` and `reader_txt`).
Each one's `test/fuzz.test.ts` replays one corpus per dialect under
`fuzz/<dialect id>/` and runs seeded byte and text mutations, spliced
across every corpus, in `npm test` (the `workerd_guests` check);
`FUZZ_SEED` and `FUZZ_ITERATIONS` pick another run.

- **Parsing** (`parseFile` in each guest's `src/dialects.ts`, under
  `crates/bookclerk-plugins/optional/metadata-files` (`libation_json`,
  `opf`, `kodi_album_nfo` and `cue`) and `integration-audiobookshelf`).
  Oracle, written from the ABI's record rules (`validate_metadata_file_record` and
  `check_record_against_dialect`) and the dialect's manifest row: a file
  is refused only with `invalid_params`. Otherwise the record passes every
  rule the host applies, states only the row's fields and credit roles,
  and is the same on a second parse.
- **Rendering** (`renderFile`), for every row with `writes = true` (`opf`,
  `kodi_album_nfo`, `cue` and all four Audiobookshelf dialects), over every
  mutated file as the existing file, with a random record and field list
  (and, for `metadata_files`, a random list of audio files). Oracle: a
  refusal only for a file `parse` also refuses, an answer that would pass
  the size cap, a request the format cannot hold (chapters for a CUE sheet
  with several files and no audio files, past a file of unknown length or
  after the last file's known end;
  an audio file name with a double quote), a `metadata.json` number whose
  exact value a double cannot keep, an existing Audiobookshelf file with
  bytes that decode only to U+FFFD, or an Audiobookshelf NFO description
  line it would read as an underline. Chapters laid out across several
  audio files are not compared, because the CUE reader leaves them
  unstated. Otherwise the answer is within
  `MAX_METADATA_FILE_BYTES`, and a re-parse passes the same rules, reads
  back each field it was asked to write, and reads every other field (and
  every credit role the request does not state) as the existing file did.
  The Audiobookshelf oracle also checks that each such field stays stated
  or absent as before.
- **XML scanning** (`parseXml` in `src/xml.ts`), under every XML dialect's
  parse and render. It decodes only XML's five entities and numeric
  references, refuses a document type with an internal subset and nesting
  past 64 levels, so no file can make it expand; the parse oracle above
  covers it.

### Egress bridge User-Agent rule

The workerd egress bridge (`bridge/egress.js`, one file synced into
`bookclerk-workerd` and both plugin SDKs) decides on every hop whether a
request keeps the guest's own `User-Agent` (`keepsOwnUserAgent`) and sets
the host's agent otherwise (`withUserAgent`). The policy comes from the
host, but a request's host comes from the guest.
`packages/plugin-sdk/scripts/test-egress-user-agent.mjs` replays
`egress_user_agent_corpus/` and runs seeded mutations of hosts, patterns
and agents (`npm run test:egress-user-agent`, in the `plugin_sdk_abi`
check); `FUZZ_SEED` and `FUZZ_ITERATIONS` pick another run.

- Oracle, written from the [User-Agent](/docs/plugins/capabilities/index.md#user-agent)
  rule: host and pattern are trimmed once, lose trailing dots and are
  lowercased, and one holding `%` or non-ASCII never matches. A `*` pattern
  never matches. `*.suffix` matches the suffix and any name whose labels end
  with its labels; any other pattern matches exactly. The guest's agent is
  sent only when it set one and the host matches; otherwise the policy's
  agent, or the bridge's fallback when the policy names none.

## Still to add

These are tracked in the fuzzing ADR's follow-ups:

- a full RPC session against a scripted guest;
- Audible CENC/DASH parsing;
- package extraction;
- naming paths;
- the node frames' per-body checks beyond parsing (upload manifests,
  storage keys) and the frames' HTTP side;
- media chapter math;
- backup import.

## Corpora, oracles and replay

Seed corpora are checked in under `fuzz/corpus/<target>/`. Ordinary tests
replay them in pull-request CI (`tests/fuzz_corpus.rs` in the owning
crate), so a fixed crash stays fixed without a nightly toolchain.

- **Routing.** The planner routes a corpus change to that crate's tests
  only (`relations.toml` `test_input`).
- **Shared oracles.** An oracle shared by a target and a replay test lives
  in `fuzz/oracles/<target>.rs`. Both include it with `#[path]`, so the two
  can't drift. `relations.toml` lists the oracle beside the corpus, so an
  oracle change runs that crate's tests only.
- **Dictionaries and options.** `fuzz/dictionaries/<target>.dict` and
  `<target>.options` ride beside each binary. The options file is libFuzzer
  INI with a `[libfuzzer]` section whose `max_len` matches the target's
  early-return cap.

`scripts/tests/test_ci_contract.py` fails when a target lacks a corpus, a
planner route or a replay test, or when a fuzzed crate is missing from the
pull-request workflow's path filter.

## Workflows

| Workflow | When | What |
| --- | --- | --- |
| `cflite-pr.yml` | Pull requests touching `fuzz/`, the fuzzed crates, or the ClusterFuzzLite config | 10 minutes, AddressSanitizer, code-change mode through `.github/actions/cflite-run-fuzzers`; fails on a new crash |
| `cflite-batch.yml` | Daily, and `workflow_dispatch` | 45 minutes of batch fuzzing split across targets, then [crash triage](#fuzz-crash-triage), corpus pruning and a coverage report |

The batch run's triage is private, and its corpus and coverage report are
kept as Actions artifacts.

### Artifact lookups

Both workflows run the same pinned run-fuzzers image, entered through
`scripts/cflite_artifacts.py`, which changes how ClusterFuzzLite finds a
target's corpus or the coverage report:

- **Stock lookup.** ClusterFuzzLite lists every artifact in the repository,
  100 per page, until a name matches. It stops paging only after as many
  artifacts as the first page counted. When none matches (a target added
  since the last batch run) and artifacts expire meanwhile, it keeps
  asking for empty pages. One pull request run asked for 4,840 pages and
  used up the repository's hourly `GITHUB_TOKEN` budget, so other
  workflows failed until the hour reset.
- **Bounded lookup.** Each lookup is one request for the artifacts with
  that name, newest first. The newest one that has not expired and
  downloads from this repository is used; a target without one fuzzes
  from its seeds, as before. Listing every artifact is disabled.

If the image no longer has the methods the script replaces, the job fails
instead of fuzzing with the stock lookup. Bump the image digest in both
actions and `cflite-batch.yml` together, then re-test.

> [!IMPORTANT]
> A crash found by the scheduled run is handled as a security report,
> unless it is a failed oracle, which is filed as an issue. Either way, fix
> it first, then land its reproducer as `fuzz/corpus/<target>/regression_*`
> in the fixing pull request.

The build config lives in `.clusterfuzzlite/` (`Dockerfile`, `build.sh`,
`project.yaml`). `build.sh` packages every target `cargo fuzz list`
reports.

The scheduled **workerd pin bump** job
(`.github/workflows/workerd-pin-bump.yml`) also compiles
`bookclerk-workerd` and `bookclerk-plugin-abi`, so it installs `capnproto`
before `cargo build` when a pin bump is eligible.

## Add a target

1. Add a `[[bin]]` to `fuzz/Cargo.toml`.
2. Add a seed folder under `fuzz/corpus/`.
3. Add a `test_input` route in `scripts/ci_plan/relations.toml`.
4. Add a replay test in the owning crate.
5. Put the crate on `cflite-pr.yml`'s path filter.
6. Add a row to the [boundary table](#rust-boundaries).
7. Add an entry to `fuzz/boundaries.toml` (see
   [triage](#fuzz-crash-triage)).

To reproduce locally, run this from `fuzz/` (it needs `capnp` on `PATH`):

```sh
cargo +nightly fuzz run <target>
```

## Fuzz-crash triage

Anyone can read the job logs and artifacts of this public repository. The
stock ClusterFuzzLite `run_fuzzers` action prints each crash's stack and
libFuzzer output (small crashing inputs included) to the log, and uploads
the reproducer as an artifact. So the scheduled workflow never uses it.
Instead:

1. **Fuzz privately.** `batch`, `prune` and `coverage` run the same pinned
   run-fuzzers image through `.github/actions/cflite-private-run`, which
   runs `scripts/fuzz-crash-triage.py run`. That is the image's own mode,
   with its output in a private log and its crash upload disabled.
   - Corpus and coverage artifacts are unchanged (looked up as in
     [Artifact lookups](#artifact-lookups)), and pull-request fuzzing still
     logs and uploads its crashes. The log shows a crash count.
   - Timeout inputs are kept (`REPORT_TIMEOUTS`), so triage sees them.
   - Every scheduled build sets `bad-build-check: false`, because that
     check runs each target briefly and prints its output to the log.
   - `prune` gives each target `fuzz-seconds` (3600) divided by the
     targets left as a hard deadline for merging its corpus. A target
     whose merge runs past it, or fails, keeps its corpus as it was, and
     the log says so; the other targets are still pruned and the job
     passes. Any other error fails it.
2. **Seal the crashes.** When `batch` kept crashes, it seals them with its
   log (`FUZZ_CRASH_BUNDLE_KEY`, `scripts/osv-remediation-bundle.sh`) as
   the `fuzz-crashes-<sanitizer>` artifact, kept 7 days.
3. **Reproduce and classify.** `triage` rebuilds the fuzzers from the same
   commit and runs `fuzz-crash-triage.py reproduce` in the same image. Each
   crash is:
   - re-run, and dropped unless it reproduces;
   - minimized with `-minimize_crash`, except a timeout, out of memory or
     leak, which keeps its original input;
   - classified as a sanitizer error, panic, stack overflow, out of memory,
     timeout, leak, fatal signal, or unknown;
   - marked as a failed oracle when the panic is raised from code under
     `fuzz/`, which decides how it is filed;
   - deduplicated by target, kind and the top three frames of the code
     under test. A crash with no usable frames, such as a wall-clock
     timeout, is keyed by its input instead, so unrelated ones stay apart.

   The output is sealed as `fuzz-triage-<sanitizer>`, kept 90 days.
4. **File.** `fuzz-crash-triage.py file`, with the
   [automation App](/docs/contributing/automation/index.md#automation-app) token, files each
   signature not already on record. A signature is on record when a hidden
   `<!-- fuzz-crash-signature: … -->` marker is in any repository
   advisory, or in a `fuzz-crash` issue that is open or was closed as not
   planned or duplicate. See [What gets filed](#what-gets-filed).

### What gets filed

- **A draft security advisory** for every crash that isn't an oracle
  failure, before the first release too. Drafts are private, and filing
  them proves the path. A maintainer reviews and publishes.
- **An issue** for a failed oracle (a panic raised from
  `fuzz/fuzz_targets/` or `fuzz/oracles/`). That is a bug rather than a
  vulnerability. The issue names the target, its boundary and the sealed
  bundle.
- **Nothing new** for a crash already on record as an advisory.

The draft advisory carries the stack, the reproducer (base64, up to
4 KiB) and a reproduce command.

- **Affected packages** are the target's artifacts from
  `fuzz/boundaries.toml`, with a proposed range `<= <newest tag>` that a
  maintainer confirms, because the crash reproduced on `main`, not on the
  release.
- **Before the first release** no range is proposed. Prereleases count as
  releases; drafts don't.
- **Default severity** is high for memory-safety errors on either side, a
  fatal signal, and anything unrecognized. A denial of service (panic,
  stack overflow, out of memory, timeout) is medium in host code and low
  inside a guest. A leak is low.

> [!NOTE]
> A high-severity advisory asks for the fix in a temporary private fork.
> A maintainer starts that fork, because it needs the Administration
> permission the App doesn't have.

An issue closed as completed doesn't suppress a later identical crash,
because that is a regression. One closed as not planned or duplicate does.

While an advisory on record is still a draft, a run that sees the crash
again rewrites only the automated part of its description: a new
reproducer, boundary or default severity mapping. That is the same way the
[OSV advisories](/docs/contributing/automation/index.md#osv-advisories) work. Closed and published
advisories are never touched.

### Boundaries file and bundles

`fuzz/boundaries.toml` maps every target to its crate, who controls its
input, whether it runs host-side, and which shipped artifacts contain it.
`scripts/tests/test_fuzz_crash_triage.py` fails when a target in
`fuzz/Cargo.toml` or in the [boundary table](#rust-boundaries) lacks an
entry. So adding a target means adding one there too.

To read a bundle, download the artifact and run:

```sh
BUNDLE_KEY=<passphrase> scripts/osv-remediation-bundle.sh open sealed.bin <dir>
```

Replace `<passphrase>` with the bundle key maintainers keep, and `<dir>`
with a new folder to open the bundle into. `sealed.bin` is the file the
artifact download writes.

- A new sanitizer needs a matrix entry in both jobs.
- A new run-fuzzers image digest must be bumped in the action and in
  `triage` together, and re-tested. The wrapper patches one method of the
  image's Python package, and refuses to fuzz when that method is missing.

## Next steps

- [ADR: Untrusted-input fuzzing](/docs/adr/untrusted-input-fuzzing/index.md): why
  every boundary is fuzzed.
- [Continuous integration](/docs/contributing/ci/index.md): how replay tests are planned.
- [Repository automation](/docs/contributing/automation/index.md): the App and the advisory
  workflows triage shares.
