open-standards/wai/catalogue/README.md

# The operation catalogue

Every operation of the WAI toolchain, once. [`ops.json`](ops.json) is written by
`wai ops export` from the table in `wai-rs/src/catalogue.rs`, and CI fails when the two differ
(`.github/workflows/wai-catalogue.yml`). Do not edit it by hand: change the table, then

```bash
cd wai/wai-rs && cargo run -q --no-default-features --bin wai -- ops export --out ../catalogue/ops.json
```

[`mcp.json`](mcp.json) (format `wai.mcp-tools/1`) lists the tools `wai mcp` serves, each with its
name, its operation, its toolset and its input schema, in the order `tools/list` gives them. A test
of the binary holds it to the tools' table (`wai-rs/src/bin/wai_cli/mcp/tools.rs`), byte for byte;
change the table, then

```bash
cd wai/wai-rs && WAI_MCP_EXPORT_WRITE=1 cargo test --no-default-features --features mcp --bin wai the_committed_export_is_the_tables
```

`wai breaking` reads both files, the base's against the working tree's (surface `catalogue`,
category `api`): a change to a stable operation, its flags, its `--json` output or its tool is a
break; a change to a preview one is owed a changelog line that names it; an operation's id or a flag
renamed with the old one kept, deprecated, is no break, and removing that old one waits for its
deprecation window ([VERSIONING.md](../VERSIONING.md)).

## An operation

An operation is named `noun.verb`: lowercase ASCII, a singular noun, and a verb from naming
rule N3's closed list (create, list, show, update, delete, check, verify, run, build, export,
import, start, stop, join, leave, grant, invite, revoke, rotate, tail, search, test, load, encode,
decode, inspect, wrap, unwrap, fetch, generate, promote, rollback, lock, upgrade, setup, guide,
stream, upscale, tonemap, doctor), never a near-synonym (`get`, `describe` and `info` are `show`; `keygen`, `init` and
`new` are `create`; `up` is `start`, as in `wai dev`). A command a person already types keeps its spelling as the operation's
command line: `wai hello` is `toolchain.test`, `wai stage refine` is `stage.encode`.

The list as approved with WAI toolchain v1 ended at `stream`. Two verbs joined it after the wai
0.4.0 release, with `media.upscale` and `media.tonemap`: `upscale` and `tonemap`. Each names an
exact derivation, an output any verifier recomputes bit for bit from the input and the parameters
its record names (extensions/exact-upscale.md, extensions/exact-tonemap.md), and no approved verb
names that: `encode` and `decode` run a codec, and `generate` makes media from a description. One more joined
with `toolchain.doctor`: `doctor` says what state a machine is in and what to do about each thing
it finds, where `check` and `verify` hold something named on the command line to a rule. A verb
joins the list the same way: in `VERBS` (wai-rs/src/catalogue.rs), this paragraph and the
list above. The doors' check (`scripts/check-wai-ops-doors.py`) keeps no list of its own: it
reads `VERBS` and `NEAR_SYNONYMS` from that file, and a test of the catalogue holds this
paragraph's lists to them.

An entry (format `wai.ops/1`) carries:

| Member | Meaning |
|---|---|
| `id` | `noun.verb` |
| `summary` | One line, for help, docs and the search |
| `cli`, `aliases` | The command line today, and other spellings; every operation also answers to `wai <noun> <verb>` |
| `usage` | The synopsis |
| `placement` | `local`, `client` (on this machine, against a service it names), `service` or `both` |
| `effect` | `reads`, `runs`, `writes-project`, `writes-target` or `destructive` |
| `dry_run` | Whether it takes `--dry-run`: every operation whose effect is not `reads` |
| `confirm` | When it waits for `--yes`: `never`, `when-replacing-an-unnamed-file`, `when-replacing-a-file`, `when-changing-the-target-or-replacing-a-file` or `always` |
| `route` | Its HTTP method and path, for an operation that runs on a service |
| `toolset` | `core`, `dev`, `app`, `quantum` or `maintainer` |
| `stability` | `stable`, `preview` or `internal` |
| `input`, `output`, `stream` | JSON Schemas: its arguments (each with the flag or position that gives it), the `data` of its `--json` envelope, and each line of a streaming operation |
| `since`, `deprecated` | The toolchain version that first carries it; its replacement, once renamed |
| `receipt` | Whether it writes a signed receipt or record that a `verify` operation checks |
| `needs` | The build features it needs (`all` or `any` of them) |
| `names` | Its name in each door |

## One name in every door

| Door | `envelope.inspect` | Held by |
|---|---|---|
| CLI | `wai inspect`, `wai envelope inspect` | the `wai` binary's tests (`tests/cli_ops.rs`) |
| MCP | `envelope_inspect` | `scripts/check-wai-ops-doors.py` |
| HTTP API | `operationId: envelope.inspect` | `scripts/check-wai-ops-doors.py` |
| C | `wai_envelope_inspect` | `scripts/check-wai-ops-doors.py` |
| Rust | `wai::envelope::inspect` | |
| JavaScript, Swift, Kotlin | `wai.envelope.inspect` (Swift and Kotlin: `WaiEnvelope.inspect`) | `scripts/check-wai-ops-doors.py` (Swift, Kotlin) |

A door that does not carry an operation yet is reported as such by the check; a door that
names one differently fails it. In the C header and the native sinks, a name is an operation's
when its noun is a catalogue noun and its verb an operation verb; the codec, envelope and sink
functions that are not operations are library API.

## The service an operation acts on: `--target`

`--target` is one input wherever it is taken (`catalogue::TARGET`, which a test of the catalogue
holds every such input to), and only on an operation placed off this machine: the service the
operation acts on, named by a target's name or by its `http://` or `https://` address. An
operation that needs a service and is given none takes the target `wai target use` chose; one for
which a service is optional (`wai enrolment create`, which writes a file without one) never does.

| What | Command | Operation |
|---|---|---|
| Keep a name for an address, in the project's `wai.json` (`targets`) or in your own list; `--read-only` refuses every change | `wai target add <name> --url <URL> [--read-only] [--user]` | `target.create` |
| The target taken where none is named | `wai target use <name> \| --none` | `target.update` |
| Every target, where it is kept, and whether a key is kept for it | `wai target list` | `target.list` |
| Remove one | `wai target remove <name> [--user]` | `target.delete` |
| Keep the key a service takes, read from standard input, for its origin | `wai auth login --url <URL> [--store keychain\|file]` | `credential.create` |
| The origins a key is kept for, never a key | `wai auth status` | `credential.list` |
| Remove a kept key | `wai auth logout --url <URL>` | `credential.delete` |

`--target local` is the development room on this machine: the room service of the stack `wai dev`
runs from the directory a command runs in, found by its record (`.wai/dev/stack.json`) and asked
first whether it is that stack (exit 5, `stack-not-found`, when none is recorded; exit 6,
`stack-stale`, when the stack recorded there is not running). `wai room show --target local` reads
its room, and `wai room grant --target local` asks it for a grant, waiting for `--yes` as any change
does.

A target is never kept with a key, and `wai.json` refuses a target's member that is a key's by its
name. A key is kept outside the project, for its origin: in the login keychain on macOS, else in a
file of the configuration directory (`$WAI_CONFIG_DIR`, `$XDG_CONFIG_HOME/wai` or `~/.config/wai`)
that only its owner reads. `WAI_TOKEN`, when set, is sent instead of a kept key. A key goes as
`Authorization: Bearer`, over `https://` or over `http://` to this machine alone (exit 3,
`key-over-plaintext`, otherwise), and is never printed, put in a plan, a log or an error: what a
service answers is shown with any key it repeats replaced by `<key>`.

An operation of a service's API (one with a `route`) answers on the command line to its mechanical
form, which sends its request to its route under the target's address: `wai room show --target
staging` is `GET <staging's address>/room`. `--query <name>=<value>` adds a query parameter and
`--body <json>|@<file>|-` a request's body, as the service's API document states them. The
service's answer is the envelope's `data` (`target`, `request`, `status`, `body`, and `key`: where
the key came from, `WAI_TOKEN` or `kept`, or null), and a refusal is an exit: 401 or 403 is 3, 404 is 5,
400, 413, 415 or 422 is 2, 409 or 410 is 1, 429, 502, 503 or 504 is 6, any other 7. A change waits for
`--yes`, a dry run names the request and sends nothing, and a read-only target refuses it (exit 3,
`target-read-only`) before anything is sent. A name no list holds is exit 5, `target-not-found`.

`wai mcp --target <name|url>` serves the same operations as tools, each sent to that target alone:
those that read it always, those that change it where the server may (a target on this machine, or
another with `--allow-write`; never with `--read-only` or to a read-only target). They are the
target's tools, not a toolset's: an entry's `mcp` (and the export's `doors.mcp`) says whether a
toolset serves it. The catalogue itself is two of the `core` tools: `ops_search` (`ops.search`),
the operations that match a task, and `ops_show` (`ops.show`), one operation's entry, with whether
the server's build holds it.

**A build that holds every operation.** `--features full` (wai-rs/Cargo.toml) names each feature an
operation's `needs` names, and where an operation needs any one of several, the one that needs no
system library: `cargo install --features full` holds every command. The catalogue's tests hold the
list to the table both ways (an operation a build with it does not hold, and a feature in it that no
operation needs, each fail them), and wai-catalogue.yml runs the command line's tests in that build.

**Folds: another program of the toolchain, through `wai`.** An operation whose behaviour is a program
of the toolchain with a command line of its own runs that program as itself: `audit.create`,
`audit.check` and `audit.verify` are `wai-audit report|check|verify`, `service.start` (`wai serve <role>`) is the role's
program `wai-<role>` started from its configuration (with `--check`, the program reads it and starts
nothing), and the `quantum` operations are `wai-quantum`'s verbs, which are also the tools of the
`quantum` toolset, each answered by `wai-quantum mcp`. What such an operation prints and its exit
status are the program's; the program is the flag its entry names, its `WAI_<NAME>_BIN` variable,
the program beside `wai`, or on `PATH`, and one that is not there is exit 5, `program-not-found`.
`wai quantum` reaches only the verbs the catalogue lists: any other is exit 5,
`operation-not-found`. `cmcd.encode`, `cmcd.decode` and `cmcd.verify` are the delivery-telemetry
corpus's tool compiled into `wai`, the same code `wai_telemetry` runs; `score.build` and
`score.decode` also answer to `wai media score build|render`.

## Agent rules

Every command of the catalogue keeps them.

| Exit | Meaning |
|---|---|
| 0 | Done; every check held |
| 1 | Ran, and a check failed |
| 2 | Usage error or invalid input |
| 3 | Authentication or permission |
| 4 | Confirmation required; nothing changed |
| 5 | Not found (file, target, room, operation, or a build feature) |
| 6 | Target unavailable; safe to retry |
| 7 | Internal error |

With `--json`, stdout holds one envelope and logs stay on stderr; without it the output is text,
on a terminal or not. One module holds these rules for every command
(`wai-rs/src/bin/wai_cli/dx/envelope.rs`).

```json
{ "wai": "envelope/1", "op": "envelope.wrap", "ok": false, "exit": 4,
  "error": { "code": "confirmation-required", "message": "out.wai exists, and the command line did not name it as the output (-o); nothing was changed",
             "hint": "read the proposed changes, then run the confirming command", "retryable": false },
  "proposed": [ { "replace": "out.wai" } ],
  "confirm": "wai wrap wai.text.zstd p.bin --yes" }
```

A success carries `data`: the command's own JSON where it has one, `{"text": ...}` otherwise.
A failure carries its `exit`; a check that failed (exit 1) carries both `error` and `data`. A dry run adds `"dry_run": true`
and the `plan` of what it would write, and of each request it would send to a service it names
(a fleet service), none of them sent. A check an operation could not run, because a tool, a checkout
or a build feature it needs was not found, says `not checked` and is never counted as holding: with
no check failed the exit is 5, with `error.code` `not-checked` and the report in `data`. `--yes` is never implied; off a terminal, or with
`--no-input`, a change that waits for it exits 4. `--confirm` is a deprecated spelling of `--yes`
that does the same; the export lists the agent flags (`agent_flags`) with it as a deprecated
alias.

`--fields a,b.c`, with `--json`, keeps only those members of `data`: each a member's name, or a
dotted path to a member within one (`body.room`; a path may begin `data.`), of each item when
`data` is a list. A member that is not there is left out. The envelope's own members, `wai`, `op`,
`ok`, `error`, `exit`, `dry_run`, `plan`, `proposed` and `confirm`, are always kept, whatever is
named: `--fields` never hides whether an operation held or why it did not. A stream's lines are
written as the operation writes them. Without `--json`, or without a value, it is a usage error.

`wai` sends nothing off your machine unless you name a remote service.