docs(api): catalog the /meta unrecognised-type-spelling refusal (#9193)

[os-project-manager]

Fixes#9193

metaUrlSpellingRefusal's envelope — INVALID_REQUEST / 400 / "not a recognised spelling" — ships on the wire and was documented nowhere in content/docs/**. A caller that sent a declined spelling got a status and a code it could not look up. This adds the catalog entry, plus a pointer from the Metadata API page.

Docs-only. No changeset; skip-changeset applied.

What the refusal actually declines — measured, not paraphrased

The card warned this entry could be born wrong in two ways. Both were checked against origin/main @ 7ff5aa294 before a word was written.

It is a MISSPELLING refusal, not a PLURAL refusal. Probed live against the built @objectstack/spec (dist/shared/index.mjs), not read off a card:

viewes REFUSE {"declared":"view","hint":"views"}
objectes REFUSE {"declared":"object","hint":"objects"}
capabilitys REFUSE {"declared":"capability","hint":"capabilities"}
fieldes REFUSE {"declared":"field","hint":"fields"}
views null fold-> view
objects null fold-> object
translations null fold-> translation
fields null fold-> field
fieldz null fold-> fieldz [unmintable]
theme null fold-> theme

Recognised plurals fold and are served. What is refused is a spelling that resolves to no type at all while reaching for a type the platform declares. The entry says exactly that, and carries a callout making the non-claim explicit — this is the premise corrected at #9180 comment 5310461296, and the entry is written to that correction rather than to the ruling's original framing.

The refusal is genuinely wire-reachable, which the entry's example depends on: the :type path parameter matches any string, and deps.errorFromThrown passes the thrown code/status through (packages/runtime/src/http-dispatcher.ts:764). INVALID_REQUEST is registered to @objectstack/metadata-protocol in ERROR_CODE_LEDGER, so it is not demoted to declaredCode. The example body is the shape buildApiError actually emits — { success: false, error: { code, message, httpStatus } } — rather than a sketch of the EnhancedApiError schema.

⭐ The entry states no verb count, deliberately

I re-derived the count instead of inheriting "nine": every call site of canonicalizeMetaRequestType, which is the function holding the refusal.

Nine on current origin/main — getMetaItems, getMetaItem, getMetaItemLayered, getMetaItemCached, saveMetaItem, publishMetaItem, rollbackMetaItem, diffMetaItem, deleteMetaItem. The card's inherited figure happens to be right today.

And it is already stale in flight. PR #9191 is open (draft, not merged as of this writing) and routes auditMetaItem, historyMetaItem and findReferencesToMeta through the same boundary — taking it to twelve the moment it lands. Writing "nine" would have shipped a sentence with a known expiry date.

So the entry hard-codes no count, per the #9175 lesson: a prose sentence stating a count is a declared-vs-enforced pair with no enforcement. Nothing here needs the number — a caller looking up a code needs the cause, the correction and the retry verdict, none of which are per-verb. This is the cheaper phrasing and the more accurate one.

One accuracy trap avoided while writing it: translations and fields are recognised spellings, but they do not fold on the three unrouted verbs today (that is precisely the #9157 defect). So the entry quantifies over no verbs at all — it says recognised plurals are folded at the boundary, and illustrates with views and objects, which fold everywhere. A sentence saying "on every verb" would have been false.

Scope

• ⛔ Not a rider on Three read-side /meta verbs (history, audit, references) never reach canonicalizeMetaRequestType — they still derive their key from the MANIFEST map #9157 — the absence predates it and covers the whole family.
• ⛔ Not step ③ of [Ruling] The /meta type segment is ALWAYS singular — retire every plural spelling, no exception, in three steps #9180.metadata-api.mdx's singular/plural statement (line 26 and following) is untouched. My addition to that page sits in the ## Metadata section intro, is only about the refusal, and makes no claim about which spelling is canonical — so the step ③ card still owns that paragraph whole. Worth noting the re-weigh landed while this was in flight ([Ruling] The /meta type segment is ALWAYS singular — retire every plural spelling, no exception, in three steps #9180 comment 5311434183): step ③'s breaking half is not ruled and the fold stays as a compatibility tolerance, which the entry is consistent with — it documents the fold as serving, not as deprecated.
• ⛔ No sweep. Two adjacent gaps found while working were filed, not fixed (below).
• No Quick Reference row was added: those rows are read by check:error-status-conformance as per-code claimed statements over the standard vocabulary, and a route-scoped ledger code does not belong in a category summary.

Findings filed, not fixed

• The /meta "is not a metadata type" refusal (#8421) has no catalog entry either — it shares INVALID_REQUEST / 400 with the spelling refusal and is told apart only by message #9243 — the sibling /meta refusal ("is not a metadata type", meta-unknown-type-namespace: a /meta type name that is not a plural of anything still mints a namespace — PUT /meta/fieldz/x answers 200 #8421) has no catalog entry either, and shares INVALID_REQUEST / 400 with this one. This forced one bounded judgement: an entry keyed on the code that claimed the code means "misspelling" would have been false, so the entry ends with a disambiguation naming the sibling by its message opener. That line is the minimum that keeps this entry true; the sibling's own entry — with its two non-obvious exemptions — is The /meta "is not a metadata type" refusal (#8421) has no catalog entry either — it shares INVALID_REQUEST / 400 with the spelling refusal and is told apart only by message #9243's.
• [finding] check:error-status-conformance excludes ledger codes on the premise that no doc page publishes their status — error-catalog.mdx now does, and that status is reconciled by nothing #9244 (finding) — check:error-status-conformance excludes ledger codes on the stated premise that "neither page publishes their status". This PR falsifies that premise: the catalog now publishes 400 for a ledger code, and nothing reconciles it. The gate passes correctly by its own rules; the bound is what went stale.

Verification — all at 586e4cb21 (final commit)

Gates derived with node scripts/pm/dispatch-gates.mjs against the actual changed paths, then re-run after the final commit:

check:nul-bytes PASS
check:doc-anchors PASS
check:role-word PASS
check:docs-redirects PASS
check:error-status-conformance PASS
check:docs-audit-scope PASS
check:empty-state (spec) PASS
check:liveness (spec) PASS
check:strictness-ledger (spec) PASS
check:variant-docs (spec) PASS

check:doc-anchors is not named by the derivation — added because the diff introduces a cross-page fragment link. It is the gate that actually verifies the new anchor resolves (241 internal #fragment link(s) ... all resolve to a real heading), so the link was confirmed by a gate rather than by slug guesswork. check:error-status-conformance and check:docs-audit-scope are the two the derivation matched on error-catalog.mdx specifically.

The pinned spelling contract was run as the premise check before any edit: packages/spec/src/shared/metadata-url-spelling.test.ts — 20 passed.

⚠️The docs-drift advisory is structurally silent here and that is not evidence of correctness.scripts/docs-audit/affected-docs.mjs derives affected pages from changed package sources; this diff changes no package, so it reports 0 docs ... across 0 changed package(s) and prints no "what this run could not see" section. For a docs-only diff it has nothing to say in either direction.

---

Generated by Claude Code