From e68376d486759cf5c534832ee4aec93d017888a4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 25 Aug 2026 23:43:20 +0000 Subject: [PATCH] docs(api): retire the compound-name spelling from the live docs (#12176 stage 4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stage 4 of the #12176 maintainer-ruled retirement of slash-bearing metadata item names. Stage 1 (#12194) declared the item-name grammar and refuses every slash-bearing name at the publish door; stage 3 (#12195) un-mounted the three compound `:section` arities. These two pages were still teaching both. content/docs/api/client-sdk.mdx: - The `meta.getItem` example addressed `'views/all_leads'` and promised compound names "pass through unencoded". Both halves are dead: the name is refused at the publish door, and #12195 put encodeURIComponent on every /meta item address, so there is no unencoded pass-through left. Respelled to the grammar's own published exemplar, `crm_lead.pipeline` under type `view` — which is exactly ViewItemNameSchema's `.` identity, so the example teaches the enforced shape rather than a new one. content/docs/api/error-catalog.mdx: - The unmintable-type entry documented TWO exemptions reaching the door. The compound-arity exemption is gone from the source (it was removed by #12194, not #12195 — `refuseUngrammaticalMetaItemName` runs before the probe and refuses every slash-bearing name), so the page has been describing a served behaviour that no longer exists. Reduced to the one surviving exemption, with a short retirement note so a caller who knew the old behaviour is not left guessing. - The residue that exemption documented — `PUT /meta/fieldz/a/b` being accepted — is closed with it, and the page now says so. - Two plural references to "the exemptions" corrected to the singular. No changeset: docs-only, releases nothing (the `skip-changeset` case the workflow prescribes). No ablation is owed — the change is prose and one example, and the example is covered by check:skill-examples' semantic pass. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01H9StxQgG2DPA26XzZZqnJB --- content/docs/api/client-sdk.mdx | 4 ++-- content/docs/api/error-catalog.mdx | 35 +++++++++++++++--------------- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx index 032275974a..0f5429e048 100644 --- a/content/docs/api/client-sdk.mdx +++ b/content/docs/api/client-sdk.mdx @@ -213,8 +213,8 @@ if (cached.notModified) { // Get auto-generated view const listView = await client.meta.getView('account', 'list'); -// Compound names (sub-resources) pass through unencoded -const view = await client.meta.getItem('object', 'views/all_leads'); +// Sub-resource identity is DOT-qualified — `.`, never a `/` +const view = await client.meta.getItem('view', 'crm_lead.pipeline'); // Per-item draft lifecycle (ADR-0033) await client.meta.publishItem('object', 'account', { message: 'go live' }); diff --git a/content/docs/api/error-catalog.mdx b/content/docs/api/error-catalog.mdx index bf5911fc17..aead001c2a 100644 --- a/content/docs/api/error-catalog.mdx +++ b/content/docs/api/error-catalog.mdx @@ -573,7 +573,7 @@ the segment reaches for no declared type, so there is nothing to suggest. See the [Metadata API](/docs/api/metadata-api). **Retry:** `no_retry` — replaying the same request against the same deployment returns the same `400`. ⚠️ That is stability, not determinism: the verdict is not a pure function of -the type segment, and the exemptions below decide whether it fires at all. +the type segment, and the exemption below decides whether it fires at all. `PUT /api/v1/meta/fieldz/showcase_task.title` answers `400` with: @@ -589,21 +589,22 @@ the type segment, and the exemptions below decide whether it fires at all. ``` -**Two shapes reach this door and are served, not refused** — neither of them visible in -the message, so a caller who does not read this entry finds them by collision: - -1. **Compound arity.** A `name` containing `/` exempts the request, because at that arity - the `:type` segment carries an **object** name rather than a type claim: - `PUT /meta/lead/views/all_leads` is `type='lead'`, `name='views/all_leads'`, and no - static contract can enumerate the objects a deployment carries. Residue, stated rather - than hidden: `PUT /meta/fieldz/a/b` is therefore **accepted** — at that arity `fieldz` - is a claim about an object, not about a metadata type. The exemption is the **arity**, - not the name: `PUT /meta/lead/all_leads` is still refused. -2. **Pre-existing namespace.** If `sys_metadata` already holds rows under that type key, - the write proceeds. The **store** decides this, never the caller — the probe runs only - after the static verdict has already fired, and it asks whether the *namespace* exists, - not whether your item does. This is what keeps rows minted before this refusal existed - editable by the tooling that copies and re-saves them. +**One shape reaches this door and is served, not refused** — it is not visible in the +message, so a caller who does not read this entry finds it by collision: + +- **Pre-existing namespace.** If `sys_metadata` already holds rows under that type key, + the write proceeds. The **store** decides this, never the caller — the probe runs only + after the static verdict has already fired, and it asks whether the *namespace* exists, + not whether your item does. This is what keeps rows minted before this refusal existed + editable by the tooling that copies and re-saves them. + +A second exemption used to sit beside it and is **retired**: a `name` containing `/` used +to skip this verdict entirely, because at the compound `/meta/:type/:section/:name` arity +the `:type` segment carried an **object** name rather than a type claim. Item names may no +longer contain `/` — they are lowercase snake_case segments, optionally dot-qualified +(`crm_lead`, `crm_lead.pipeline`), refused at the publish door otherwise — and the compound +arities are un-mounted. The residue that exemption used to document is closed with it: +`PUT /meta/fieldz/a/b` is no longer accepted, and no longer reaches this verdict at all. ⇒ **The same segment can be refused on one deployment and served on another, depending on stored state.** A `400` here is a statement about *this* deployment, not a portable @@ -622,7 +623,7 @@ it. **Why it is refused rather than passed through.** A namespace nothing reads and nothing serves is not a harmless extra key — it accumulates silently, and every row in it is invisible to the tooling that lists, validates and ships metadata. Refusing at the mint -door is what stops the first row from being written; the exemptions above are what keep +door is what stops the first row from being written; the exemption above is what keeps that refusal from stranding the rows written before it existed. ⛔ **Not this error:** a segment that *misspells a type the platform declares* —