Retire compound-name metadata addressing — un-mount the three :section arities and unify SDK URL spelling (#12176 stage 3) (#12378)

* feat(rest,runtime,client)!: retire compound-name metadata addressing

Stage 3 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, so the compound arities addressed only
names that can no longer be created — this removes them.

packages/rest:
  - Un-mount the three compound arities: GET and PUT /meta/:type/:section/:name
    and GET /meta/:type/:section/:name/published. Drop their three route-ledger
    rows and the ordering pins that existed only because the three-segment
    compound route was a CATCH-ALL shadowing every literal sibling.

packages/runtime:
  - Un-fold the dispatcher: the /published branch requires exactly three
    segments and the item branch exactly two, instead of re-joining every
    trailing segment into one slash-bearing key.
  - Decode the :name segment. This dispatcher splits the RAW path and nothing
    decodes for it, unlike the Hono routes in packages/rest — measured, not
    assumed. Without it a pre-grammar residue row would be addressable through
    REST and not through the dispatcher, breaking #12194's landed acceptance
    criterion that stored junk names stay listable and clearable. The sibling
    domains/packages.ts already decodes its own id segments this way.

packages/client:
  - One URL spelling: encodeURIComponent on every /meta item address, closing
    the 10-unencoded / 4-encoded split. Encoding a name that satisfies #12194's
    grammar is a no-op, so this is byte-identical for every writable name; a
    residue name now reaches the single-segment door as %2F rather than forking
    the request onto a second door.
  - Correct the docblocks that promised unencoded compound pass-through, and
    the #11712 mode carve-out, which is closed at the source rather than here.

Capability is re-expressed, not removed: %2F matches the single-segment
pattern and Hono decodes the parameter back to the stored spelling, so residue
rows still read, write and delete through the surviving doors.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H9StxQgG2DPA26XzZZqnJB

* test(rest,runtime,client): rework the compound-arity pins for the removal

Every pin that measured the retired compound-name arities is REWORKED, never
silenced. Two shapes, chosen per file by what is actually still true:

INVERTED — files whose subject was a shadowing or divergence hazard now pin
the ABSENCE of the arity, because a re-mount is how the hazard returns and an
order pin phrased against a retired route would go green while the retirement
is undone:
  - meta-route-registration-order: the three-segment catch-all ordering pins
    become "no compound `:section` arity is mounted", plus a companion pin that
    the literals it used to shadow are all still mounted.
  - meta-item-layered-route, meta-plural-i18n, rest-server-meta-write-org-scope,
    meta-compound-save-{mode,force}-parity, meta-compound-save-and-reset-
    capability-gate, meta-501-envelope: same inversion, each keeping the reason
    the original pin existed (a re-mounted door arrives ungated, org-blind, and
    reading neither `?force` nor `?mode` until someone re-derives that work).

RE-AIMED at the surviving door — coverage that was never about the spelling:
  - the full #11712 `?mode` and #11095 `?force` contracts, the #6877 repeated-
    parameter guard, the #7019 capability gate and the #8842 falsy-body hole
    now run against `/meta/:type/:name`.
  - meta-published-overlay's residue-row read drives the single-segment
    `/published` route with the decoded name — the pin that the retirement
    costs no capability.
  - client URL pins invert to `%2F`, each with a control proving a grammar-legal
    name is byte-identical on the wire.

NEW post-removal pins, ADR-0112 code AND status on every one:
  - the compound path answers `404 ROUTE_NOT_FOUND` at the dispatcher;
  - the ENCODED spelling still reaches the item-name grammar's `400
    INVALID_REQUEST`, so "the route is gone" and "the name is illegal" stay
    distinguishable;
  - `DELETE` on a compound path answers 404, not the 405 its two-segment
    address gets — the two refusals are different facts.

Also: the meta domain's tail `{ handled: false }` was unreachable dead code
until this card (0, 1 and — through the fold — every 2+ segment path were all
covered). Un-folding makes it reachable, so it becomes a LOCATED
`routeNotFound` rather than letting the adapter answer an anonymous 404 on the
very shape this retirement newly produces. Same form `domains/ai.ts` and
`domains/share-links.ts` already use.

Changeset: minor on rest/runtime/client with the BREAKING route table and the
FROM → TO spelling, per the launch-window convention.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H9StxQgG2DPA26XzZZqnJB

* test(rest,dogfood): pay the six new TEST_DEBT errors and rework the dogfood compound-door rows (#12195)

The pin rework left four dead constants and two off-type boot calls in the
rest test layer — TEST_DEBT measured 161 against the frozen 155; all six are
fixed, none ledgered. The dogfood anonymous-deny table drops the retired
compound-save row (its registered-door leg asserts .not.toBe(404), which is
what a retired route answers) and gains the retired-door case: the compound
spelling must 404 for anonymous and member alike, since an auth floor only
speaks for a door that exists. The authz-conformance matrix note re-tallies
six -> five with the retirement named.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H9StxQgG2DPA26XzZZqnJB

---------

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

Author: os-trump

.changeset/retire-compound-name-metadata-addressing.md

@@ -0,0 +1,57 @@
+---
+'@objectstack/rest': minor
+'@objectstack/runtime': minor
+'@objectstack/client': minor
+---
+
+Retire compound-name metadata addressing (`/meta/:type/:section/:name`)
+
+Stage 3 of the maintainer-ruled retirement of slash-bearing metadata item names.
+Stage 1 declared the item-name grammar and refuses every slash-bearing name at
+the publish door, so the routes removed here addressed only names that can no
+longer be created.
+
+**BREAKING — three public REST routes stop answering:**
+
+| stops answering | use instead |
+| :-- | :-- |
+| `GET /api/v1/meta/:type/:section/:name` | `GET /api/v1/meta/:type/:name` |
+| `PUT /api/v1/meta/:type/:section/:name` | `PUT /api/v1/meta/:type/:name` |
+| `GET /api/v1/meta/:type/:section/:name/published` | `GET /api/v1/meta/:type/:name/published` |
+
+Each retired route folded its `:section` and `:name` segments back into one
+slash-bearing key (`views/all_leads`) that the protocol layer then treated as a
+single opaque string — the section half was never stored, filtered or
+enumerated. A request to a retired path now answers `404 ROUTE_NOT_FOUND`.
+
+The `@objectstack/runtime` dispatcher stops folding in the same way: its
+`/meta` handler requires exactly two path segments for an item and three for
+`…/published`, instead of re-joining every trailing segment. A `/meta` path
+that matches no route now answers a located `404 ROUTE_NOT_FOUND` rather than
+falling through to the adapter's anonymous 404.
+
+**FROM → TO for callers.** Address every item through the single-segment route
+and percent-encode the name:
+
+```
+GET /api/v1/meta/lead/views/all_leads     →  GET /api/v1/meta/lead/views%2Fall_leads
+```
+
+`@objectstack/client` now calls `encodeURIComponent` on every `/meta` item
+address, so SDK callers need no change: the SDK already sends the new spelling.
+Encoding is a **no-op** for every name the item-name grammar admits (lowercase
+snake_case segments, optionally dot-qualified), so the bytes on the wire are
+unchanged for every name that can be written today.
+
+A pre-grammar **residue** row whose stored name contains a slash remains
+readable, writable and deletable: `%2F` matches the single-segment pattern and
+the parameter is decoded back to the stored spelling before the handler runs.
+Nothing that could be stored has become unaddressable.
+
+Two SDK doc comments that promised "compound names pass through unencoded"
+(`meta.getPublished`, `meta.publishItem`) are corrected, and the
+`SaveMetaItemOptions.mode` carve-out — `{ mode: 'draft' }` was silently ignored
+at the compound door and published live — is closed at the source: there is one
+door, and it reads every member of the options bag.
+
+<!-- adr-0087: not-required (already-registered metadata-item-name-grammar-enforced) the stage-1 semantic entry already names this exact surface — "the compound `:type/:section/:name` fold" — and carries the re-authoring prescription (dot-qualified, or flattened with an underscore). This stage removes the routes that fold; it adds no new authorable shape and no second migration prescription. -->

packages/client/src/client.test.ts

@@ -321,20 +321,46 @@ describe('ObjectStackClient', () => {
         );
     });
 
-    it('meta.getItem/saveItem pass compound names through unencoded (reaches /meta/:type/:section/:name)', async () => {
+    it('[#12195] meta.getItem/saveItem ENCODE the name — one spelling, one door', async () => {
         const { client, fetchMock } = createMockClient({ success: true, data: { name: 'views/all_leads' } });
+        // ⚠️ This pin is INVERTED from what it was, and the inversion is the
+        // card. It used to require the slash to survive UNENCODED, so the
+        // request would reach the compound handler
+        // `/meta/:type/:section/:name` instead of collapsing onto the
+        // two-segment route. #12176 retired compound-name addressing: that
+        // handler is gone, so `%2F` is now the correct and only spelling.
+        //
+        // Encoding is a no-op for every name #12194's grammar admits (snake
+        // case, optionally dot-qualified), so this changes nothing a legal
+        // caller sends. What it changes is a pre-grammar residue name: it now
+        // reaches the surviving door with its slash intact as `%2F`, which Hono
+        // decodes back to `views/all_leads` — the capability that used to
+        // require a second route.
         await client.meta.getItem('object', 'views/all_leads');
-        // The slash must survive: %2F would collapse the request onto the
-        // 3-segment /meta/:type/:name route and miss the compound handler.
         expect(String(fetchMock.mock.calls[0][0])).toBe(
-            'http://localhost:3000/api/v1/meta/object/views/all_leads',
+            'http://localhost:3000/api/v1/meta/object/views%2Fall_leads',
         );
         await client.meta.saveItem('object', 'views/all_leads', { label: 'All leads' });
         expect(String(fetchMock.mock.calls[1][0])).toBe(
-            'http://localhost:3000/api/v1/meta/object/views/all_leads',
+            'http://localhost:3000/api/v1/meta/object/views%2Fall_leads',
         );
         expect(fetchMock.mock.calls[1][1].method).toBe('PUT');
     });
+
+    it('[#12195] a LEGAL name is byte-identical before and after the encoding change', async () => {
+        // The other half: unifying on `encodeURIComponent` must not have moved
+        // the wire for any name a caller can actually write. Dotted and flat
+        // snake_case both pass through untouched.
+        const { client, fetchMock } = createMockClient({ success: true, data: {} });
+        await client.meta.getItem('object', 'crm_lead');
+        await client.meta.getItem('view', 'crm_lead.pipeline');
+        expect(String(fetchMock.mock.calls[0][0])).toBe(
+            'http://localhost:3000/api/v1/meta/object/crm_lead',
+        );
+        expect(String(fetchMock.mock.calls[1][0])).toBe(
+            'http://localhost:3000/api/v1/meta/view/crm_lead.pipeline',
+        );
+    });
 });
 
 describe('Reports namespace (#3587 gap closure)', () => {
@@ -2662,14 +2688,15 @@ describe('[#11391] meta.saveItem query string (unscoped client)', () => {
         );
     });
 
-    it('a compound name keeps its unencoded slash AND gets the query string', async () => {
+    it('[#12195] a slash-bearing name is ENCODED and still gets the query string', async () => {
         const { client, fetchMock } = createMockClient({ success: true });
         await client.meta.saveItem('object', 'views/all_leads', { label: 'All leads' }, { force: true });
-        // The slash must still survive (%2F would collapse this onto the
-        // 3-segment route and miss `PUT /meta/:type/:section/:name`), and the
-        // compound door reads `?force` too since #11095.
+        // Inverted by #12195: the slash used to be required to survive raw so
+        // the request reached `PUT /meta/:type/:section/:name`, which had read
+        // `?force` since #11095. That door is retired; `%2F` reaches the
+        // surviving door, which has always read `?force`.
         expect(String(fetchMock.mock.calls[0][0])).toBe(
-            'http://localhost:3000/api/v1/meta/object/views/all_leads?force=true',
+            'http://localhost:3000/api/v1/meta/object/views%2Fall_leads?force=true',
         );
     });
 });
@@ -2878,16 +2905,15 @@ describe('[#11713] meta.saveItem sends the If-Match header (unscoped client)', (
         expect(JSON.parse(init.body)).toEqual({ name: 'customer' });
     });
 
-    it('OCC-guards a COMPOUND name too — unlike `mode`, this reaches both doors', async () => {
+    it('[#12195] OCC-guards a slash-bearing name too, at the one surviving door', async () => {
         const { client, fetchMock } = createMockClient({ success: true });
         await client.meta.saveItem('object', 'views/all_leads', { label: 'All leads' }, { ifMatch: OCC_TOKEN });
-        // The compound-name door `PUT /meta/:type/:section/:name` reads
-        // `if-match` and strips ETag quotes exactly as the single-segment door
-        // does — measured in rest-server.ts. `mode` is the member that does NOT
-        // reach it; this one does, so the slash must survive AND the pin must
-        // ride along.
+        // This case used to say "unlike `mode`, this reaches BOTH doors" — the
+        // compound door read `if-match` while never reading `mode`. There is
+        // one door now, so every member of the options bag reaches it and the
+        // per-member carve-out is gone. The name is encoded like every other.
         expect(String(fetchMock.mock.calls[0][0])).toBe(
-            'http://localhost:3000/api/v1/meta/object/views/all_leads',
+            'http://localhost:3000/api/v1/meta/object/views%2Fall_leads',
         );
         expect(headersOfCall(fetchMock)['If-Match']).toBe(OCC_TOKEN);
     });

packages/client/src/index.ts

@@ -601,11 +601,11 @@ export interface SaveMetaItemOptions {
      * empty spelling would pin the write against the empty string and refuse
      * every save with a 409 the caller never asked for.
      *
-     * ✅ REACHES BOTH DOORS — unlike `mode` below. The compound-name twin
-     * `PUT /meta/:type/:section/:name` reads `if-match` and strips ETag-style
-     * quotes exactly as the single-segment door does, so
-     * `saveItem('object', 'views/all_leads', item, { ifMatch })` is
-     * OCC-guarded like any other save.
+     * [#12195] There is ONE door now. The compound-name twin
+     * `PUT /meta/:type/:section/:name` — which this note used to pair with —
+     * is retired, and every name reaches `PUT /meta/:type/:name`
+     * percent-encoded, so `if-match` behaviour no longer varies by how the
+     * name is spelled.
      *
      * Same member name, same header, same truthy guard as the sibling
      * first-party `@object-ui/data-objectstack` `MetadataClient.save`, whose
@@ -645,21 +645,21 @@ export interface SaveMetaItemOptions {
      * on the wire that the server ignores. Same shape the first-party
      * `@object-ui/data-objectstack` `MetadataClient.save` already uses.
      *
-     * ⚠️ COMPOUND NAMES DO NOT STAGE. `mode` reaches only the single-segment
-     * `PUT /meta/:type/:name`. Its compound-name twin
-     * `PUT /meta/:type/:section/:name` — the door a `name` containing a slash
-     * lands on, e.g. `saveItem('object', 'views/all_leads', item)` — never
-     * reads this parameter, so `{ mode: 'draft' }` there is IGNORED and the
-     * write is PUBLISHED LIVE, answered 200. It is not refused; there is no
-     * signal at the call site. Filed as objectstack#11712 and deliberately not
-     * repaired from this side: threading it is the route's decision, and a
-     * client-side guess would be a second place the two doors disagree.
+     * [#12195] REACHES EVERY SAVE — the carve-out this note used to carry is
+     * GONE, and it is worth recording why rather than deleting it silently.
      *
-     * ⛔ Do not "fix" this by rejecting compound names here. `force` and
-     * `packageId` DO reach both doors (measured: the compound handler reads
-     * and threads `?force` since objectstack#11095 and `?package` alongside
-     * it), so refusing the whole bag on a compound name would break the two
-     * parameters that work in order to warn about the one that does not.
+     * `mode` used to reach only the single-segment `PUT /meta/:type/:name`.
+     * A `name` containing a slash landed on the compound-name twin
+     * `PUT /meta/:type/:section/:name`, which never read this parameter — so
+     * `{ mode: 'draft' }` there was IGNORED and the write was PUBLISHED LIVE,
+     * answered 200, with no signal at the call site (objectstack#11712).
+     *
+     * Two changes closed it at the source rather than from this side. Stage 1
+     * (#12194) made a slash-bearing name unwritable at all, and this stage
+     * retired the twin and unified this file on `encodeURIComponent`, so every
+     * save now arrives at the one door that reads `mode`. A name that would
+     * once have forked to the silent-publish door is now refused `400
+     * INVALID_REQUEST` by the grammar — loud, at the door, before any write.
      */
     mode?: 'draft' | 'publish';
 }
@@ -911,7 +911,7 @@ export class ObjectStackClient {
         const params = new URLSearchParams();
         if (options?.packageId) params.set('package', options.packageId);
         const qs = params.toString();
-        const url = `${this.baseUrl}${route}/${type}/${name}${qs ? `?${qs}` : ''}`;
+        const url = `${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs ? `?${qs}` : ''}`;
         const res = await this.fetch(url);
         return this.unwrapResponse<GetMetaItemResponse>(res);
     },
@@ -953,10 +953,16 @@ export class ObjectStackClient {
         // omits the `headers` key altogether, so a save without `ifMatch`
         // hands `fetch` the same `init` it always did.
         const headers = metaSaveHeaders(options);
-        // `type`/`name` stay UNENCODED — a compound name's slash must survive
-        // so the request reaches `PUT /meta/:type/:section/:name` instead of
-        // collapsing onto the 3-segment route (pinned in client.test.ts).
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}${query}`, {
+        // [#12195] ENCODED, like every other `/meta` item address in this file.
+        // This site used to leave `type`/`name` RAW so a compound name's slash
+        // would survive into a separate path segment and reach
+        // `PUT /meta/:type/:section/:name`. That door is retired, and encoding
+        // is now the single spelling: a legal name (#12194's grammar — snake
+        // case, optionally dot-qualified) contains nothing `encodeURIComponent`
+        // alters, so this is byte-identical for every name that can be written,
+        // and a pre-grammar residue name reaches the single-segment door with
+        // its slash intact as `%2F` instead of forking the request.
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${query}`, {
             method: 'PUT',
             body: JSON.stringify(item),
             ...(headers ? { headers } : {}),
@@ -1090,13 +1096,19 @@ export class ObjectStackClient {
      */
 
     /**
-     * ADR-0033: the published version of a metadata item. Compound names are
-     * passed through unencoded (e.g. `getPublished('lead', 'views/all_leads')`),
-     * matching how `getItem` addresses sub-resources.
+     * ADR-0033: the published version of a metadata item.
+     *
+     * [#12195] The name is percent-encoded, like every other `/meta` item
+     * address in this file. This docblock used to promise the opposite — that
+     * a compound name passed through UNENCODED, `getPublished('lead',
+     * 'views/all_leads')`, so its slash would reach the compound arity
+     * `GET /meta/:type/:section/:name/published`. That arity is retired and a
+     * slash-bearing name is refused at the publish door (#12194), so there is
+     * one spelling and one door.
      */
     getPublished: async (type: string, name: string) => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/published`);
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/published`);
         return this.unwrapResponse<any>(res);
     },
 
@@ -1177,7 +1189,7 @@ export class ObjectStackClient {
      */
     getReferences: async (type: string, name: string) => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/references`);
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`);
         return this.unwrapResponse<any>(res);
     },
 
@@ -1200,15 +1212,16 @@ export class ObjectStackClient {
     getAudit: async (type: string, name: string, opts?: { limit?: number }) => {
         const route = this.getRoute('metadata');
         const qs = opts?.limit !== undefined ? `?limit=${opts.limit}` : '';
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/audit${qs}`);
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/audit${qs}`);
         return this.unwrapResponse<any>(res);
     },
 
     /**
      * ADR-0033: promote a single item's pending draft overlay to live —
      * the per-item flow beside `packages.publishDrafts`' package-scoped one.
-     * 404 [no_draft] when there is nothing to publish. Compound names pass
-     * through unencoded, like `getItem`.
+     * 404 [no_draft] when there is nothing to publish. [#12195] The name is
+     * percent-encoded, like `getItem` — this line used to promise unencoded
+     * pass-through for compound names, whose arity is now retired.
      *
      * The resolved `version` is the ADR-0008 optimistic-concurrency token, the
      * same carrier `saveItem` returns and with the same job: pass it back as
@@ -1229,7 +1242,7 @@ export class ObjectStackClient {
         opts?: { message?: string },
     ): Promise<PublishMetaItemResponse> => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/publish`, {
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`, {
             method: 'POST',
             body: JSON.stringify(opts?.message ? { message: opts.message } : {}),
         });
@@ -1241,7 +1254,7 @@ export class ObjectStackClient {
      */
     rollbackItem: async (type: string, name: string, toVersion: number, opts?: { message?: string }) => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/rollback`, {
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`, {
             method: 'POST',
             body: JSON.stringify({ toVersion, ...(opts?.message ? { message: opts.message } : {}) }),
         });
@@ -1258,7 +1271,7 @@ export class ObjectStackClient {
         if (opts?.from !== undefined) params.set('from', String(opts.from));
         if (opts?.to !== undefined) params.set('to', String(opts.to));
         const qs = params.toString();
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}/diff${qs ? `?${qs}` : ''}`);
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/diff${qs ? `?${qs}` : ''}`);
         return this.unwrapResponse<any>(res);
     }
   };
@@ -5581,7 +5594,7 @@ export class ScopedProjectClient {
       const params = new URLSearchParams();
       if (options?.packageId) params.set('package', options.packageId);
       const qs = params.toString();
-      const res = await this.parent._fetch(this.url(`/meta/${type}/${name}${qs ? `?${qs}` : ''}`));
+      const res = await this.parent._fetch(this.url(`/meta/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs ? `?${qs}` : ''}`));
       return this.parent._unwrap<GetMetaItemResponse>(res);
     },
     /**
@@ -5608,7 +5621,7 @@ export class ScopedProjectClient {
       // Header half of the same bag, through the same one builder the twin
       // calls — see {@link metaSaveHeaders}.
       const headers = metaSaveHeaders(options);
-      const res = await this.parent._fetch(this.url(`/meta/${type}/${name}${query}`), {
+      const res = await this.parent._fetch(this.url(`/meta/${encodeURIComponent(type)}/${encodeURIComponent(name)}${query}`), {
         method: 'PUT',
         body: JSON.stringify(item),
         ...(headers ? { headers } : {}),