84b630956a
enrolment.create, enrolment.list, report.create and report.export join the catalogue as the other operations are: placed on the client against a fleet service, with their effect, toolset, input and output schemas, receipt and the features they need (fleet for the two that sign or verify). wai enrolment|report run through the door, and the fleet's command module keeps the agent rules of dx/envelope.rs instead of its own copy of them: the envelope with --json, every file through out.rs and every request to the service named in a dry run's plan and not sent (out::would_send), and --yes before the service is changed or a file replaced, exit 4 off a terminal with the proposal and the confirming command. A catalogue entry now says when it waits for confirmation (Op::confirms: never, a file the command line did not name, any file, the target or a file, always), and the rules refuse a change to a target that does not wait and a read that does. The export carries it and the agent flags (AGENT_FLAGS), from which wai --help is written: --yes is the one confirmation flag, and --confirm, which wai conform, wai setup-agent and the fleet took, is its deprecated spelling, still accepted, so named in help, in every confirming operation's help and in the export. wai conform confirms through the same module. wai verify's entry names the conformance results and fleet bundles it reads. Co-Authored-By: Claude Opus 5.5 <[email protected]>
5 KiB
The operation catalogue
Every operation of the WAI toolchain, once. 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
cd wai/wai-rs && cargo run -q --no-default-features --bin wai -- ops export --out ../catalogue/ops.json
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), never a near-synonym (get, describe and info are show; keygen, init and
new are create). 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. Its 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.
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).
{ "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. --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.
wai sends nothing off your machine unless you name a remote service.