docs(deployment): name the /meta/diagnostics query refusals and the canonical stats key (#27959)

domain:devx#2 · os-justin · session_01QSeKYmTYfaPbLQD4BJfomW

Refs #27632 (the #27620 half: the three value refusals and the canonical
`stats` key; the #27913 parameter-name refusal stays on the card until
#27913 lands)

Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么:`validating-metadata.mdx` 的 `GET /api/v1/meta/diagnostics`
参数表补上三种 400 拒收(未知 `type`、`severity`、`package`),并说明 `stats` 按规范类型名作键。
- 为什么改:#27620 之后该路由已拒收这三类错误值，文档没写，读文档的 AI 和 CI 作者仍以为拼错会得到空的「全部通过」。
- 风险与回滚：仅文档，一个文件、一节;回滚即 revert 本 PR,不影响任何发布包。
- 先看:`content/docs/deployment/validating-metadata.mdx` 的 diagnostics
一节(参数表与其后两段)。
- 两分钟验证:`git diff origin/main --
content/docs/deployment/validating-metadata.mdx`,预期只见该节的表格加一列、两段新文字。
- 需要你做的：无，席位落地。

## What changes

The `GET /api/v1/meta/diagnostics` section of
`content/docs/deployment/validating-metadata.mdx` now states what the
route does since #27620, each sentence written from the code on
`origin/main` (`ed0e71db94`):

- The query table gains a column naming each parameter's `400
INVALID_REQUEST` refusal:
- `severity`: any value other than `error` / `warning`
(`packages/rest/src/meta-collection-routes.ts`, the severity check).
- `type`: a misspelling of a declared type, whose message names the
accepted spellings (`canonicalizeMetaRequestType` in
`packages/metadata-protocol/src/protocol.ts`), or a name that is neither
a declared type nor in the deployment's live type set
(`refuseUnknownMetaListType` in
`packages/rest/src/meta-item-read-gate.ts`). A live type outside the
static contract still answers 200.
- `package`: a package that is not installed and that no swept item is
bound to
(`packages/metadata-protocol/src/protocol-meta-diagnostics.ts`). An
installed package with no items answers zero counts. `all` sweeps every
package (`metaItemPackageBinding`).
- An empty value keeps the default. Every refusal uses the nested `{
error: { code, message } }` envelope, and a repeated parameter answers
`VALIDATION_ERROR` in the same envelope (`refuseRepeatedQueryParams`).
- `stats` and each entry's `type` use the canonical type name, so
`type=views` answers under `stats.view`, the same as `type=view`
(`canonicalMetaUrlType` in the sweep).
- The CI-gate sentence now says that a misspelled `type` or `package`
answers the 400 rather than an empty sweep.

Left out: the refusal of an unknown query parameter NAME (#27633 / PR
#27913). That PR was still open on `origin/main` `ed0e71db94` when this
branch was cut. Card comment 6514340216 carries the text to add once it
lands.

## Tests

Docs only, so there is no test to run. The route's own pins in
`packages/rest/src/rest-meta-diagnostics-unknown-params.test.ts`
(unchanged) back each documented clause: the three refusals, the
near-miss message naming `'view'`, the repeated-parameter
`VALIDATION_ERROR`, the canonical `stats.view` for `type=views`, and the
preservation cases (empty severity, `package=all`, an installed package
with no items, items bound to an uninstalled package, a live type
outside the static contract).

## Acceptance notes

- No finding filed.

## Verification

Measured at head `26a0c3bd1b` (objectstack-ai/objectstack).

<details><summary>Derived gate families: 43 derived, 43 run, all exit
0</summary>

- Derivation: `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`, exit 0, 43 commands, change set of 1 path
(+15 / -7).
- Each command's exit code was written to disk before any pipe. On the
first pass, four gates refused with exit 3, PREREQUISITE NOT MET
(unbuilt `@objectstack/formula`, `@objectstack/lint` and client dist):
`check:doc-formula-expressions`, `check:doc-security-posture`,
`check:skill-examples` and `check:docs-transcript-drift`. After `turbo
run build` of those closures under the verify lock (VERDICT command-exit
0, 38/38 tasks), all four re-ran with exit 0.
- `check:doc-authoring`: exit 0 ("70 published skill files clean",
"19837 customer-facing string(s) ... clean").
- `check:nul-bytes`: exit 0.
- Reconciliation: `dispatch-gates.mjs --repo objectstack-ai/objectstack
--ran` (each line recorded with its exit code) answered "43 derived
famil(ies) accounted for — 43 run, 0 NOT-MEASURED (a DERIVED zero — all
43 recorded an exit code and none of them is 3)".

</details>

<details><summary>Not measured locally</summary>

- NOT MEASURED: CI's `Build Docs` and `Plan Test Core shards` jobs, and
the type-check lanes. The derivation names no local invocation for them,
so they are left to CI.

</details>

---
_Generated by [Claude
Code](https://claude.ai/code/session_01QSeKYmTYfaPbLQD4BJfomW)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

content/docs/deployment/validating-metadata.mdx

@@ -804,15 +804,23 @@ validated after, so the envelope describes the effective item.
 
 `GET /api/v1/meta/diagnostics` sweeps every type and item in one request:
 
-| Query | Default | Effect |
-| :--- | :--- | :--- |
-| `severity` | `error` | `error` returns invalid items only; `warning` also returns warning-only items |
-| `type` | — | One metadata type |
-| `package` | — | One package |
+| Query | Default | Effect | Refused with `400 INVALID_REQUEST` |
+| :--- | :--- | :--- | :--- |
+| `severity` | `error` | `error` returns invalid items only; `warning` also returns warning-only items | Any other value |
+| `type` | every type | One metadata type, singular or plural | A misspelling of a declared type (the message names the accepted spellings), or a name that is neither a declared type nor a type this deployment carries |
+| `package` | every package | One package; `all` sweeps every package | A package that is not installed and that no item is bound to |
+
+An empty value keeps the default. Every refusal answers in the nested
+`{ error: { code, message } }` envelope; a repeated parameter (`?type=view&type=object`)
+is refused the same way with `VALIDATION_ERROR`. An installed package with no items
+answers zero counts, not a refusal.
 
 The response carries `entries` (each `{ type, name, diagnostics }`), `total`,
-`scannedTypes`, `scannedItems` and per-type `stats`. `total === 0` is a usable CI gate
-against a running server; add `severity=warning` to hold warnings to the same bar.
+`scannedTypes`, `scannedItems` and per-type `stats`. `stats` and each entry's `type` use
+the canonical type name: `type=views` answers under `stats.view`, exactly as `type=view`
+does. `total === 0` is a usable CI gate against a running server: a misspelled `type` or
+`package` answers the 400, never an empty sweep that reads as `total === 0`. Add
+`severity=warning` to hold warnings to the same bar.
 Studio shows the same envelope on the metadata directory, each type's list, each
 item's edit page and the governance page (`…/metadata/_diagnostics`).