fix(metadata): route the three read-side /meta verbs through the canonical type boundary (#9157)

[os-zhuang]

Fixes#9157

Step ① of the maintainer ruling in #9180 (2026-08-16): the /meta type segment is singular, always, no exception.

auditMetaItem, historyMetaItem and findReferencesToMeta each opened by deriving their type key from PLURAL_TO_SINGULAR — the MANIFEST-COLLECTION map #7894 moved this boundary off — instead of calling canonicalizeMetaRequestType, which the nine sibling /meta verbs already call. That one call carries both the URL spelling map andmetaUrlSpellingRefusal, and the refusal is the half these three could never reach: it lives inside the function they skipped.

⛔ Steps ② (the /meta/objects/:name/state/:field route rename) and ③ (docs + retiring PLURAL_TO_SINGULAR as a fold) are not in this PR. #9180 requires the three steps to stay independently revertible. #9174 remains open and is not addressed here.

---

⚠️ The card's premise, corrected by measurement

The filing card asserted that PUT /meta/views/all_leads is "refused 400 by the same deployment for the same spelling", and the dispatch summarised the deliverable as three GET routes going "200-empty → 400". The first is false and the second is true only for one of two classes. Measured on origin/main before writing any code:

metaUrlSpellingRefusal('views') -> null # recognised plural: FOLDS, never refused
metaUrlSpellingRefusal('translations') -> null # ditto
metaUrlSpellingRefusal('viewes') -> { declared: 'view', hint: 'views' }

views is in META_URL_TO_SINGULAR, so it folds — on the write verbs today just as on the read verbs after this PR. The refusal class is misspellings of a declared type, not recognised plurals. The premise still stands where it matters (three verbs genuinely skip the boundary, and the empty-accumulator harm is real), so this is a correction rather than a falsification — but the delivered wire change is two-shaped, not one:

caller's :type	before	after
viewes — unrecognised spelling of a declared type	200, empty body	400 INVALID_REQUEST, naming view and views
translations / fields / seeds / external_catalogs — recognised plurals of the four manifest-ABSENT types	200, empty body	200 with the real rows
views — recognised plural, manifest-PRESENT	unchanged	unchanged
fieldz — reaches for no declared type	unchanged	unchanged (the refusal stays narrow, so a plugin kind can never trip it)

Both rows close the harm #9180 named — "nothing depends on this" delivered right before a rename or delete. One does it by refusing loudly; the other by finally answering truthfully. Retiring the recognised plurals themselves is step ③, and a pin (theRecognisedPluralsAreNotRefused) asserts they are still accepted so this PR cannot be read as having bundled it.

⭐ The population, re-derived rather than taken from the card

The card hand-listed "nine fold, three do not". Derived mechanically from the source instead — every class method taking a request with a requiredtype: string, which is the shape a /meta/:type path segment arrives as:

• 9 folded: getMetaItems, getMetaItem, getMetaItemLayered, getMetaItemCached, saveMetaItem, publishMetaItem, rollbackMetaItem, diffMetaItem, deleteMetaItem
• 3 unfolded: auditMetaItem, historyMetaItem, findReferencesToMeta

The count is three; the card was right. The derivation is now a test, so a tenth verb arriving unfolded goes red rather than being noticed a card later.

Three methods were deliberately excluded and the exclusion is stated so it can be contested: getMetaDiagnostics, listDrafts (type?:) and migrateStoredMetadata (types?: string[]) take the type as a query-string filter, not a path segment — a different contract, and migrateStoredMetadata documents accepting both spellings on purpose.

Two measured details that invert an intuition

• On historyMetaItem the plural was a door AROUND a gate, not merely a wrong key.field declares neither allowOrgOverride nor allowRuntimeCreate, so the canonical spelling is refused by the overlay gate and never touches the store — while fields took isRuntimeCreateAllowed's no-static-registry-entry arm (the plugin path, permissive by construction) and issued a real sys_metadata_history read keyed 'fields'. Same empty body, opposite path, which is why the pins assert the KEY the store was asked for and not only the body.
• On findReferencesToMeta the refusal is the whole visible change. Every REFERENCE_PATHS key (object, view, tool, skill, flow, dashboard, page) is manifest-PRESENT and already folded, so a manifest-absent target still answers { references: [] } after this PR. That residue is asserted rather than implied, and filed separately as findReferencesToMeta answers {references: []} for every target type absent from REFERENCE_PATHS — the "Used by" panel is silent by construction for 20+ declared types #9190 (finding, unassigned) — it is a registry-coverage question, not a spelling one.

Reverse verification

Direction predicted in writing before running: plain RED (not "more diagnostics", not inverted — the refusal is thrown by the boundary itself, not by a downstream schema, so there is no ??-chain fall-through to reroute it).

Observed: plain RED, exactly as predicted. Ablating the three fold calls back to PLURAL_TO_SINGULAR[request.type] ?? request.type and re-running the pin file:

Tests 9 failed | 9 passed (18)
× every `/meta` request-boundary verb with a required `type` calls the fold — all twelve
→ expected [ 'auditMetaItem', …(2) ] to deeply equal []
× auditMetaItem > THE PIN: a manifest-ABSENT plural reads the REAL audit trail
→ expected [] to have a length of 1 but got +0
× historyMetaItem > THE OTHER PIN: the plural stops being a door AROUND the overlay gate
→ expected [ 'fields' ] to deeply equal []
… 6 more, all refusal-envelope assertions

Every predicted-green control stayed green in both directions: the anti-vacuity arm, theRecognisedPluralsAreNotRefused, all four manifest-PRESENT / plugin-shaped controls, and the honest findReferencesToMeta scope pin. The fix was committed before the ablation, so restoring it was git checkout <branch> -- <path> and git status came back clean — the restored tree is byte-identical to the committed one.

Docs

No documentation change is needed, and that was established by sweeping the whole content/docs/** corpus rather than a supplied page list. /history, /audit and /references appear in exactly two pages, neither of which makes a spelling claim (api/client-sdk.mdx:187-188 passes singular 'object'; kernel/contracts/metadata-service.mdx:85 is a bare type: string signature). Every spelling statement in the corpus — api/metadata-api.mdx:26-31 and protocol/kernel/http-protocol.mdx:877-879 — is scoped under a GET /meta/{type} heading, i.e. the listing verb, which already folded; so nothing was made false, and nothing was quietly moved toward truth either. Follow-ups filed by the PM as #9192 (the page list was wrong in both directions) and #9193 (the refusal envelope is undocumented for all twelve verbs).

Changed ranges

Declared from git diff --unified=0 origin/main, not from symbol addresses:

• packages/metadata-protocol/src/protocol.ts — 6376-6420, 13443-13476, 17883-17912

PR #9173 (#9111) is open on the same file at 11398-11470 / 11477-11496 / 11650-11666 — no overlap.

Verification — all at e96538ab7 (current head, base 671d4736f, 0 commits behind)

Re-verified after the second origin/main merge. No commit in that merge touches packages/metadata-protocol/** — but packages/spec/** moved (#9186, ObjectStackDefinitionSchema goes strict) and spec is upstream of this package, so the dependency closure was rebuilt and the suite re-run rather than carried over:

@objectstack/metadata-protocol 116 files / 1606 tests passed (at e96538ab7)

The downstream consumer sweep (--filter '...@objectstack/metadata-protocol' — dependents, not dependencies) was run at the previous head b8731f7a3 and is unchanged by this refresh, since nothing in the merge touches this package or its consumers' use of it: objectql 213 files / 3755 tests, rest 122 / 2011, runtime 165 / 2463 — all passed.

Gate union re-derived and re-run at e96538ab7, all PASS. The derivation itself was upgraded by #9188 in this very merge (it now states outright that 94 of 103 families sit in workflows with no pull_request path filter, i.e. CI schedules them on every PR):

check:changeset-gate-self-tests check:cross-package-test-inputs check:durability-log-level
check:filter-alias-parity check:objectui-changeset check:nul-bytes
check:engine-double-contract check:where-matcher check:query-options-erasure
check:type-check-coverage check-adr-0087-registration check-changeset-no-major
check-cross-package-test-inputs check-empty-changeset
check:meta-type-normalized check:error-code-casing check:error-status-conformance
check:dispatcher-error-vocabulary check:type-source-resolution check:stack-collection-maps

The last six are not named by the derivation and were read off CI's own job list (#9171 discipline). check:stack-collection-maps is new to this run and was added because its script moved in this merge and it governs PLURAL_TO_SINGULAR itself — the map this change moves off.

Type-check ratchet re-measured at the new head, not carried over: tsc --noEmit over packages/metadata-protocol reports 63 errors, still exactly the ledger's recorded number, with zero from the new test file.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx(via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/metadata-protocol)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/v9.mdx(via @objectstack/metadata-protocol)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

契约复审（needs:contract-review 清标签）— 通过

复审席：skills 席 session_017TNzEetykdh7ceZGwuAPLq（契约复审档位，非派发席，过渡期代行）。范围：契约行为增量全文（protocol.ts 三处折叠接入 + 测试断言清单 + changeset 的 wire 变更表）。

结论：

1. 接受→拒绝翻转（已声明类型的误拼 viewes：200 空体 → 400 INVALID_REQUEST 且指名 view/views）——有维护者裁决背书（2026-08-16「/meta type segment 单数,恒定」step ①），含裁决要求的引导句条件，信封整体断言（code+status+指名）。
2. 拒绝面窄口保持：plugin 形拼法（fieldz）不可误拒有钉；已识别复数不拒有反捆绑钉（step ③ 独立可回滚）。
3. manifest 缺席类修正（translations/fields 折叠后读真行）非公开面加宽——同一已声明契约下的错键修正；history 侧「复数绕门」路径同步关闭（断言读 KEY 而非只读 body，正确）。
4. 12 动词 population 由代码派生并锚定计数，三读动词与写动词信封逐字节同一。立卡时的失实主张（views 在写动词被拒）已实测证伪并钉住。
5. 未发现缺陷。 档位违规为程序性（低档派发已由派发席自报），实质变更是裁决的执行——本复审即条款②闸门放行记录，清标签后可按正常落地流程入队。

---

Generated by Claude Code