feat(MR-656): rename read/change to query/mutate with deprecation signals

HTTP server:
- Add POST /mutate as canonical write endpoint (pairs with POST /query).
- Mark POST /read and POST /change as deprecated. Three-channel signal:
  * OpenAPI: `deprecated: true` on the operation (every codegen flags
    the generated SDK method).
  * RFC 9745: response `Deprecation: true` header on every response.
  * RFC 8288: response `Link: </successor>; rel="successor-version"`
    pointing at /query and /mutate respectively.
- Share business logic across /mutate and /change via run_mutate(); the
  /change wrapper is the only place that adds the deprecation headers.
- ChangeRequest field aliases (query_source/query_name) preserved.
- AliasCommand serde now accepts `query`/`mutate` alongside `read`/`change`.

CLI:
- Promote `omnigraph query` / `omnigraph mutate` to top-level canonical
  subcommands (clap visible_alias keeps `omnigraph read` / `omnigraph
  change` working forever).
- Promote `omnigraph lint` / `omnigraph check` to top-level (was nested
  under `omnigraph query lint`, which is now a deprecated argv shim that
  rewrites to the canonical form).
- Argv-level preprocessing prints a one-line deprecation warning to
  stderr when any legacy spelling is used. Canonical names are silent.

Tests:
- Server: /mutate works, /change emits Deprecation+Link headers, /read
  emits Deprecation+Link headers, /query carries no deprecation signal.
- OpenAPI: /read and /change flagged deprecated; /query and /mutate not.
- CLI: canonical `lint` matches deprecated `query lint` / `query check`
  output; `read` / `change` print deprecation warnings.

Docs:
- cli.md: new canonical examples; "Deprecated names" migration table.
- cli-reference.md: top-level table updated; aliases.<name>.command
  accepts both legacy and canonical spellings.
- server.md: endpoint inventory shows /query and /mutate as canonical
  and /read and /change as deprecated; dedicated section explains the
  three-channel deprecation signal.
- og-cheet-sheet.md: use new `omnigraph lint` / `omnigraph check`.
- openapi.json regenerated.

Migration is purely cosmetic — every deprecated form continues to work
indefinitely; only the spelling changes.

Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>

docs/user/cli-reference.md

@@ -11,15 +11,15 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
 | `init` | `--schema <pg>` → initialize a repo (also scaffolds `omnigraph.yaml` if missing) |
 | `load` | bulk load a branch (`--mode overwrite\|append\|merge`) |
 | `ingest` | branch-creating transactional load (`--from <base>`) |
-| `read` | run named query; source via `--query <path>`, `-e`/`--query-string <GQ>`, or `--alias <name>` (exactly one) |
-| `change` | run mutation query; same `--query` / `-e` / `--alias` mutual-exclusion as `read` |
+| `query` (alias: `read`) | run named read query; source via `--query <path>`, `-e`/`--query-string <GQ>`, or `--alias <name>` (exactly one). `read` is the deprecated previous name and prints a one-line warning to stderr |
+| `mutate` (alias: `change`) | run mutation query; same `--query` / `-e` / `--alias` mutual-exclusion as `query`. `change` is the deprecated previous name and prints a one-line warning to stderr |
 | `snapshot` | print current snapshot (per-table version + row count) |
 | `export` | dump to JSONL on stdout (`--type T`, `--table K` filters) |
 | `branch create \| list \| delete \| merge` | branching ops |
 | `commit list \| show` | inspect commit graph |
 | `run list \| show \| publish \| abort` | transactional run ops |
 | `schema plan \| apply \| show (alias: get)` | migrations |
-| `query lint \| check` | offline / repo-backed validation |
+| `lint` (alias: `check`) | offline / repo-backed query validation. Replaces `query lint` / `query check`, which are kept as deprecated argv-level shims that print a one-line warning and rewrite to `omnigraph lint` |
 | `optimize` | non-destructive Lance compaction |
 | `cleanup --keep N --older-than 7d --confirm` | destructive version GC |
 | `embed` | offline JSONL embedding pipeline |
@@ -49,7 +49,10 @@ auth:
   env_file: ./.env.omni
 aliases:
   <alias>:
-    command: read|change
+    # accepted values: `read` / `query` (read alias), `change` / `mutate`
+    # (write alias). `query` and `mutate` are recommended; `read` and
+    # `change` remain accepted forever for back-compat.
+    command: read|change|query|mutate
     query: <path-to-.gq>
     name: <query-name>
     args: [<positional-name>, …]
@@ -60,7 +63,7 @@ policy:
   file: ./policy.yaml
 ```
 
-## Output formats (read command)
+## Output formats (`query` command, alias: `read`)
 
 - `json` — pretty-printed object with metadata + rows
 - `jsonl` — one metadata line then one JSON object per row

docs/user/cli.md

@@ -6,19 +6,26 @@
 omnigraph init --schema ./schema.pg ./repo.omni
 omnigraph load --data ./data.jsonl --mode overwrite ./repo.omni
 omnigraph snapshot ./repo.omni --branch main --json
-omnigraph read --uri ./repo.omni --query ./queries.gq --name get_person --params '{"name":"Alice"}'
-omnigraph change --uri ./repo.omni --query ./queries.gq --name insert_person --params '{"name":"Mina","age":28}'
+omnigraph query  --uri ./repo.omni --query ./queries.gq --name get_person --params '{"name":"Alice"}'
+omnigraph mutate --uri ./repo.omni --query ./queries.gq --name insert_person --params '{"name":"Mina","age":28}'
 ```
 
+`omnigraph query` is the canonical read command (pairs with `POST /query`);
+`omnigraph mutate` is the canonical write command (pairs with `POST /mutate`).
+The previous names `omnigraph read` and `omnigraph change` keep working as
+visible aliases — invocations emit a one-line deprecation warning to stderr
+and otherwise behave identically. See [Deprecated names](#deprecated-names)
+for the migration table.
+
 For ad-hoc reads and mutations (REPLs, AI agents, one-off scripts), pass the
 GQ source inline with `-e` / `--query-string` instead of a file path:
 
 ```bash
-omnigraph read --uri ./repo.omni \
+omnigraph query --uri ./repo.omni \
   -e 'query find($name: String) { match { $p: Person { name: $name } } return { $p.name, $p.age } }' \
   --params '{"name":"Alice"}'
 
-omnigraph change --uri ./repo.omni \
+omnigraph mutate --uri ./repo.omni \
   -e 'query add($name: String, $age: I32) { insert Person { name: $name, age: $age } }' \
   --params '{"name":"Inline","age":42}'
 ```
@@ -52,7 +59,7 @@ omnigraph-server ./repo.omni --bind 127.0.0.1:8080
 Read through the HTTP API:
 
 ```bash
-omnigraph read \
+omnigraph query \
   --target http://127.0.0.1:8080 \
   --query ./queries.gq \
   --name get_person \
@@ -65,8 +72,8 @@ and configure the matching `bearer_token_env` in `omnigraph.yaml`.
 ## Runs, Policy, And Diagnostics
 
 ```bash
-omnigraph query lint --query ./queries.gq --schema ./schema.pg --json
-omnigraph query check --query ./queries.gq ./repo.omni --json
+omnigraph lint  --query ./queries.gq --schema ./schema.pg --json
+omnigraph check --query ./queries.gq ./repo.omni --json
 
 omnigraph schema plan --schema ./next.pg ./repo.omni --json
 omnigraph schema apply --schema ./next.pg ./repo.omni --json
@@ -116,3 +123,21 @@ The config file can also define:
 
 When policy is enabled, `schema apply` is authorized through the
 `schema_apply` action and is typically limited to admins on protected `main`.
+
+## Deprecated names
+
+The CLI was renamed to align with the HTTP server's canonical endpoint
+names (`POST /query`, `POST /mutate`) and the `query` keyword in the GQ
+language. The previous spellings keep working forever; invocations emit a
+one-line warning to stderr and otherwise behave identically.
+
+| Old (deprecated)         | New (canonical)     | Migration                                                |
+|--------------------------|---------------------|----------------------------------------------------------|
+| `omnigraph read`         | `omnigraph query`   | Same flags and behavior. `read` is a visible clap alias. |
+| `omnigraph change`       | `omnigraph mutate`  | Same flags and behavior. `change` is a visible clap alias. |
+| `omnigraph query lint`   | `omnigraph lint`    | Same flags. The argv-level shim rewrites `query lint` to `lint`. |
+| `omnigraph query check`  | `omnigraph check`   | `check` is a visible alias of `omnigraph lint`. |
+
+The `command:` field in `aliases.<name>` in `omnigraph.yaml` accepts both
+`read` / `change` (legacy) and `query` / `mutate` (canonical); the two
+spellings are interchangeable on the wire via serde aliases.

docs/user/server.md

@@ -9,10 +9,11 @@ Axum 0.8 + tokio + utoipa-generated OpenAPI. Single repo per process; deploy mul
 | GET | `/healthz` | none | — | `server_health` |
 | GET | `/openapi.json` | none | — | `server_openapi` (strips security if auth disabled) |
 | GET | `/snapshot?branch=` | bearer + `read` | snapshot of branch | `server_snapshot` |
-| POST | `/read` | bearer + `read` | run named query (legacy field names `query_source`/`query_name`) | `server_read` |
-| POST | `/query` | bearer + `read` | run inline read query (clean field names `query`/`name`; mutations → 400) | `server_query` |
+| POST | `/query` | bearer + `read` | run inline read query (canonical; clean field names `query`/`name`; mutations → 400) | `server_query` |
+| POST | `/read` | bearer + `read` | **deprecated** alias of `/query` for legacy clients (legacy field names `query_source`/`query_name`, byte-stable response); response carries `Deprecation: true` + `Link: </query>; rel="successor-version"` | `server_read` |
 | POST | `/export` | bearer + `export` | NDJSON stream | `server_export` |
-| POST | `/change` | bearer + `change` | mutation (`query`/`name`; accepts legacy `query_source`/`query_name` as serde aliases) | `server_change` |
+| POST | `/mutate` | bearer + `change` | mutation query (canonical; `query`/`name`; accepts legacy `query_source`/`query_name` as serde aliases) | `server_mutate` |
+| POST | `/change` | bearer + `change` | **deprecated** alias of `/mutate` for legacy clients; response carries `Deprecation: true` + `Link: </mutate>; rel="successor-version"` | `server_change` |
 | GET | `/schema` | bearer + `read` | get current `.pg` source | `server_schema_get` |
 | POST | `/schema/apply` | bearer + `schema_apply` (target=`main`) | migrate | `server_schema_apply` |
 | POST | `/ingest` | bearer + `branch_create` (if new) + `change` | bulk load | `server_ingest` (32 MB body limit) |
@@ -41,13 +42,33 @@ request body uses clean field names that match the CLI `-e` flag and the GQ
 
 Response shape is identical to `/read` (`ReadOutput`). If the inline source
 contains mutations (`insert` / `update` / `delete`), the request is rejected
-with HTTP 400 and an error pointing the caller at `POST /change` — the
+with HTTP 400 and an error pointing the caller at `POST /mutate` — the
 read-only contract is enforced at the URL.
 
-`POST /change` accepts the same clean field names (`query`, `name`); the
-legacy field names `query_source` and `query_name` continue to deserialize as
-serde aliases so existing clients keep working without changes. `POST /read`
-is byte-stable and unchanged.
+`POST /mutate` is the canonical mutation endpoint. It accepts the same clean
+field names (`query`, `name`); the legacy field names `query_source` and
+`query_name` continue to deserialize as serde aliases so existing clients keep
+working without changes.
+
+## Deprecated names (`/read`, `/change`)
+
+`POST /read` and `POST /change` are kept for back-compat indefinitely — they
+are byte-stable on the request side and otherwise behave identically to
+`/query` / `/mutate`. They are flagged as deprecated through three independent
+channels:
+
+- **OpenAPI**: the operations carry `deprecated: true` in `openapi.json`, so
+  every OpenAPI codegen (typescript-fetch, openapi-generator, oapi-codegen,
+  …) emits a `@deprecated` marker on the generated SDK method.
+- **Response headers (RFC 9745)**: every response carries `Deprecation: true`.
+- **Response headers (RFC 8288)**: every response carries a `Link` header
+  pointing at the canonical successor:
+  `Link: </query>; rel="successor-version"` for `/read`, and
+  `Link: </mutate>; rel="successor-version"` for `/change`. SDKs and HTTP
+  proxies can pick the successor up automatically.
+
+Migration is purely cosmetic on the client side — swap the URL path, leave
+the request body and response handling alone.
 
 ## Streaming
 
@@ -61,8 +82,8 @@ Uniform `ErrorOutput { error, code?, merge_conflicts[], manifest_conflict? }` wi
 caller's pre-write view of one table's manifest version was stale.
 `ManifestConflictOutput { table_key, expected, actual }` tells the client
 which table to refresh and retry. This is the conflict shape produced by
-concurrent `/change` or `/ingest` calls landing the same `(table, branch)`
-race.
+concurrent `/mutate` (or its `/change` alias) or `/ingest` calls landing
+the same `(table, branch)` race.
 
 HTTP status codes used: 200, 400, 401, 403, 404, 409, 429, 500.
 
@@ -88,10 +109,11 @@ actors are unaffected.
 Cedar policy authorization runs **before** admission accounting so
 denied requests don't consume admission slots.
 
-Today admission gates every mutating handler: `/change`, `/ingest`,
-`/branches/{create,delete,merge}`, and `/schema/apply`. Read-only
-endpoints (`/snapshot`, `/read`, `/export`, `/branches` GET, `/commits`,
-`/schema` GET) are not admission-gated.
+Today admission gates every mutating handler: `/mutate` (and its
+deprecated alias `/change`), `/ingest`, `/branches/{create,delete,merge}`,
+and `/schema/apply`. Read-only endpoints (`/snapshot`, `/query`, `/read`,
+`/export`, `/branches` GET, `/commits`, `/schema` GET) are not
+admission-gated.
 
 ## Body limits
 
@@ -120,8 +142,9 @@ See [deployment.md](deployment.md) for token-source operational details.
 ## Not implemented (by design or "TBD")
 
 - CORS — not configured; add `tower_http::cors` if needed.
-- Rate limiting — per-actor admission control gates `/change`, `/ingest`,
-  `/branches/{create,delete,merge}`, `/schema/apply` (see "Per-actor
+- Rate limiting — per-actor admission control gates `/mutate` (alias
+  `/change`), `/ingest`, `/branches/{create,delete,merge}`,
+  `/schema/apply` (see "Per-actor
   admission control" above). No global rate limiter is configured;
   add `tower_http::limit` if a graph-wide cap is needed.
 - Pagination — none (commits/branches return everything; export streams).