Skip to content

Commit d80439f

Browse files
os-trumpclaude
andauthored
docs(api): retire the compound-name spelling from the live docs (#12176 stage 4) (#12381)
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 `<object>.<viewKey>` 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. Claude-Session: https://claude.ai/code/session_01H9StxQgG2DPA26XzZZqnJB Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9edd79f commit d80439f

2 files changed

Lines changed: 20 additions & 19 deletions

File tree

content/docs/api/client-sdk.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -213,8 +213,8 @@ if (cached.notModified) {
213213
// Get auto-generated view
214214
const listView = await client.meta.getView('account', 'list');
215215

216-
// Compound names (sub-resources) pass through unencoded
217-
const view = await client.meta.getItem('object', 'views/all_leads');
216+
// Sub-resource identity is DOT-qualified — `<object>.<viewKey>`, never a `/`
217+
const view = await client.meta.getItem('view', 'crm_lead.pipeline');
218218

219219
// Per-item draft lifecycle (ADR-0033)
220220
await client.meta.publishItem('object', 'account', { message: 'go live' });

content/docs/api/error-catalog.mdx

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -573,7 +573,7 @@ the segment reaches for no declared type, so there is nothing to suggest.
573573
See the [Metadata API](/docs/api/metadata-api).
574574
**Retry:** `no_retry` — replaying the same request against the same deployment returns the
575575
same `400`. ⚠️ That is stability, not determinism: the verdict is not a pure function of
576-
the type segment, and the exemptions below decide whether it fires at all.
576+
the type segment, and the exemption below decides whether it fires at all.
577577

578578
`PUT /api/v1/meta/fieldz/showcase_task.title` answers `400` with:
579579

@@ -589,21 +589,22 @@ the type segment, and the exemptions below decide whether it fires at all.
589589
```
590590

591591
<Callout type="warn">
592-
**Two shapes reach this door and are served, not refused** — neither of them visible in
593-
the message, so a caller who does not read this entry finds them by collision:
594-
595-
1. **Compound arity.** A `name` containing `/` exempts the request, because at that arity
596-
the `:type` segment carries an **object** name rather than a type claim:
597-
`PUT /meta/lead/views/all_leads` is `type='lead'`, `name='views/all_leads'`, and no
598-
static contract can enumerate the objects a deployment carries. Residue, stated rather
599-
than hidden: `PUT /meta/fieldz/a/b` is therefore **accepted** — at that arity `fieldz`
600-
is a claim about an object, not about a metadata type. The exemption is the **arity**,
601-
not the name: `PUT /meta/lead/all_leads` is still refused.
602-
2. **Pre-existing namespace.** If `sys_metadata` already holds rows under that type key,
603-
the write proceeds. The **store** decides this, never the caller — the probe runs only
604-
after the static verdict has already fired, and it asks whether the *namespace* exists,
605-
not whether your item does. This is what keeps rows minted before this refusal existed
606-
editable by the tooling that copies and re-saves them.
592+
**One shape reaches this door and is served, not refused** — it is not visible in the
593+
message, so a caller who does not read this entry finds it by collision:
594+
595+
- **Pre-existing namespace.** If `sys_metadata` already holds rows under that type key,
596+
the write proceeds. The **store** decides this, never the caller — the probe runs only
597+
after the static verdict has already fired, and it asks whether the *namespace* exists,
598+
not whether your item does. This is what keeps rows minted before this refusal existed
599+
editable by the tooling that copies and re-saves them.
600+
601+
A second exemption used to sit beside it and is **retired**: a `name` containing `/` used
602+
to skip this verdict entirely, because at the compound `/meta/:type/:section/:name` arity
603+
the `:type` segment carried an **object** name rather than a type claim. Item names may no
604+
longer contain `/` — they are lowercase snake_case segments, optionally dot-qualified
605+
(`crm_lead`, `crm_lead.pipeline`), refused at the publish door otherwise — and the compound
606+
arities are un-mounted. The residue that exemption used to document is closed with it:
607+
`PUT /meta/fieldz/a/b` is no longer accepted, and no longer reaches this verdict at all.
607608

608609
**The same segment can be refused on one deployment and served on another, depending on
609610
stored state.** A `400` here is a statement about *this* deployment, not a portable
@@ -622,7 +623,7 @@ it.
622623
**Why it is refused rather than passed through.** A namespace nothing reads and nothing
623624
serves is not a harmless extra key — it accumulates silently, and every row in it is
624625
invisible to the tooling that lists, validates and ships metadata. Refusing at the mint
625-
door is what stops the first row from being written; the exemptions above are what keep
626+
door is what stops the first row from being written; the exemption above is what keeps
626627
that refusal from stranding the rows written before it existed.
627628

628629
**Not this error:** a segment that *misspells a type the platform declares*

0 commit comments

Comments
 (0)