objectstack-ai
diff --git a/‎.changeset/20508-scoped-layers-link.md‎
Lines changed: 25 additions & 0 deletions b/‎.changeset/20508-scoped-layers-link.md‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎packages/rest/src/meta-item-layered-route.test.ts‎
Lines changed: 19 additions & 2 deletions b/‎packages/rest/src/meta-item-layered-route.test.ts‎
Lines changed: 19 additions & 2 deletions
diff --git a/‎packages/rest/src/meta-item-layers-deprecation-link.test.ts‎
Lines changed: 107 additions & 0 deletions b/‎packages/rest/src/meta-item-layers-deprecation-link.test.ts‎
Lines changed: 107 additions & 0 deletions
diff --git a/‎packages/rest/src/rest-server.ts‎
Lines changed: 19 additions & 1 deletion b/‎packages/rest/src/rest-server.ts‎
Lines changed: 19 additions & 1 deletion
@@ -0,0 +1,25 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): the environment-scoped `?layers=true` answer's successor `Link` names the path the request used, not the route template (#20508)
+
+Clause-②: no
+
+On `RestServer`'s environment-scoped mount (`api.enableProjectScoping`),
+`GET /api/v1/environments/env_1/meta/view/lead_all?layers=true` answered its
+`Deprecation` header with a successor `Link` naming
+`/api/v1/environments/:environmentId/meta/view/lead_all/layers`: the route
+template, with a literal `:environmentId` in it. A client that followed the
+header requested that path. The `Link` now names
+`/api/v1/environments/env_1/meta/view/lead_all/layers`.
+
+`RestServer` builds the `Link` from the request's own path, read the way the
+runtime dispatcher reads its request URL, so both transports name the successor
+the same way. The unscoped mount's `Link` is unchanged for every name that needs
+no percent-encoding. A percent-encoded name now stays encoded in the `Link`
+(`lead%20all`, where the header used to carry a raw space), because the path is
+parsed as a URL path instead of being assembled from decoded route parameters.
+A request that carries no path of its own is still answered `Deprecation: true`,
+and names no successor. The body, the status and the `Deprecation` header are
+unchanged on both mounts.
@@ -98,14 +98,19 @@ function routeFor(rest: RestServer, path: string) {
     return (rest as any).getRoutes().find((r: any) => r.method === 'GET' && r.path === path);
 }
 
-async function dispatch(protocol: any, path: string, params: any, query: any = {}) {
+/**
+ * `requestPath` is the request's own path (`IHttpRequest.path`), which the
+ * deprecated spelling's successor `Link` is built from (#20508). Omitted, the
+ * request carries none, as a request built by hand may.
+ */
+async function dispatch(protocol: any, path: string, params: any, query: any = {}, requestPath?: string) {
     const rest = new RestServer(mockServer() as any, protocol as any, ANON_API as any);
     (rest as any).resolveExecCtx = async () => ({ userId: 'u1', systemPermissions: [] });
     rest.registerRoutes();
     const route = routeFor(rest, path);
     if (!route) throw new Error(`route not registered: GET ${path}`);
     const res = mockRes();
-    await route.handler({ params, query, headers: {} }, res);
+    await route.handler({ params, query, headers: {}, ...(requestPath === undefined ? {} : { path: requestPath }) }, res);
     return { res, body: res.json.mock.calls.at(-1)?.[0] };
 }
 
@@ -204,13 +209,25 @@ describe('#5882 `?layers=true` — the deprecation window', () => {
     it('advertises the successor path in machine-readable headers', async () => {
         const { res } = await dispatch(
             baseProtocol(), ITEM_PATH, { type: 'object', name: 'customer' }, { layers: 'true' },
+            '/api/v1/meta/object/customer',
         );
         expect(res.header).toHaveBeenCalledWith('Deprecation', 'true');
         expect(res.headers.Link).toBe(
             '</api/v1/meta/object/customer/layers>; rel="successor-version"',
         );
     });
 
+    it('names no successor when the request carries no path of its own (#20508)', async () => {
+        // The `Link` is built from the path the request arrived on, never from
+        // the route template. A request with none is still deprecated, and says
+        // so, but advertises no successor it cannot locate.
+        const { res } = await dispatch(
+            baseProtocol(), ITEM_PATH, { type: 'object', name: 'customer' }, { layers: 'true' },
+        );
+        expect(res.header).toHaveBeenCalledWith('Deprecation', 'true');
+        expect(res.headers).not.toHaveProperty('Link');
+    });
+
     it('does not mark the ordinary read deprecated', async () => {
         const { res } = await dispatch(baseProtocol(), ITEM_PATH, { type: 'object', name: 'customer' });
         expect(res.header).not.toHaveBeenCalledWith('Deprecation', 'true');
 
@@ -0,0 +1,107 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#20508] The deprecated `?layers=` spelling's successor `Link` names the path
+ * the request arrived on, on BOTH `RestServer` mounts.
+ *
+ * `RestServer` built the `Link` from `metaPath`, which on the
+ * environment-scoped mount is the route TEMPLATE:
+ * `GET /api/v1/environments/env_1/meta/view/lead_all?layers=true` answered
+ * `</api/v1/environments/:environmentId/meta/view/lead_all/layers>`, a path with
+ * a literal `:environmentId` in it, so a client that followed the header asked
+ * for a path it could not mean. The runtime dispatcher builds its `Link` from
+ * the request's own URL; `RestServer` now passes the request's own path
+ * (`IHttpRequest.path`), read the same way.
+ *
+ * Driven through the real `HonoHttpServer`, the adapter `os serve` mounts,
+ * because the path is the ADAPTER's statement: a hand-built request carries
+ * whatever the test writes into it, and the encoded-name case below turns on
+ * what this adapter hands over (a `decodeURI`'d path).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { HonoHttpServer } from '@objectstack/plugin-hono-server';
+import { RestServer } from './rest-server';
+
+/** Both mounts: `optional` registers the unscoped routes beside the scoped ones. */
+const SCOPED_API = { api: { requireAuth: false, enableProjectScoping: true, projectResolution: 'optional' } };
+
+function protocol() {
+    return {
+        getDiscovery: vi.fn().mockResolvedValue({
+            version: 'v0',
+            routes: { data: '', metadata: '', ui: '', auth: '/auth' },
+        }),
+        getMetaTypes: vi.fn().mockResolvedValue([]),
+        getMetaItems: vi.fn().mockResolvedValue([]),
+        getMetaItem: vi.fn(async ({ type, name }: any) => ({
+            type, name, item: { name }, lock: 'none', editable: true, deletable: true, resettable: false,
+        })),
+        getMetaItemLayered: vi.fn(async ({ type, name }: any) => ({
+            type,
+            name,
+            code: { name },
+            overlay: null,
+            overlayScope: 'org',
+            effective: { name },
+            _diagnostics: { valid: true },
+            lock: 'none',
+            editable: true,
+            deletable: true,
+            resettable: false,
+        })),
+        findData: vi.fn().mockResolvedValue([]),
+    };
+}
+
+async function layersFlagRead(path: string) {
+    const server = new HonoHttpServer(0);
+    const p = protocol();
+    const rest = new RestServer(server as any, p as any, SCOPED_API as any);
+    (rest as any).resolveExecCtx = async () => ({ userId: 'u1', systemPermissions: [] });
+    rest.registerRoutes();
+    const res: Response = await server.getRawApp().fetch(new Request(`http://local${path}?layers=true`));
+    return {
+        status: res.status,
+        deprecation: res.headers.get('deprecation'),
+        link: res.headers.get('link'),
+        layeredReads: p.getMetaItemLayered.mock.calls.length,
+    };
+}
+
+describe('[#20508] the `?layers=true` successor `Link` names the request path', () => {
+    it('on the environment-scoped mount, names the environment the request named', async () => {
+        const answer = await layersFlagRead('/api/v1/environments/env_1/meta/view/lead_all');
+
+        // Anti-vacuity: the flag was served the layered view, so the headers
+        // below are that branch's, not an error answer's.
+        expect(answer.status).toBe(200);
+        expect(answer.layeredReads).toBe(1);
+        expect(answer.deprecation).toBe('true');
+        expect(answer.link).toBe(
+            '</api/v1/environments/env_1/meta/view/lead_all/layers>; rel="successor-version"',
+        );
+    });
+
+    it('on the unscoped mount (the control), is unchanged', async () => {
+        const answer = await layersFlagRead('/api/v1/meta/view/lead_all');
+
+        expect(answer.status).toBe(200);
+        expect(answer.layeredReads).toBe(1);
+        expect(answer.deprecation).toBe('true');
+        expect(answer.link).toBe('</api/v1/meta/view/lead_all/layers>; rel="successor-version"');
+    });
+
+    it('keeps a percent-encoded name encoded, though the adapter hands the path over decoded', async () => {
+        // Hono's `c.req.path` is `decodeURI`'d: `lead%20all` reaches the handler
+        // as `lead all`. Written into the header as it arrived, that is a space
+        // inside a URI reference; parsed as a URL path, as the dispatcher parses
+        // its request URL, it is `lead%20all` again.
+        const answer = await layersFlagRead('/api/v1/environments/env_1/meta/view/lead%20all');
+
+        expect(answer.status).toBe(200);
+        expect(answer.link).toBe(
+            '</api/v1/environments/env_1/meta/view/lead%20all/layers>; rel="successor-version"',
+        );
+    });
+});
@@ -6295,10 +6295,28 @@ export class RestServer {
                         // `Deprecation` + RFC 8288 `Link` to the successor) are the
                         // ones the runtime dispatcher's item read asks too, so the
                         // deprecated spelling is one answer on both transports.
+                        //
+                        // [#20508] The `Link` names the path THIS request arrived
+                        // on (`IHttpRequest.path`), read the way the dispatcher
+                        // reads its request URL (`requestedItemPath`, runtime
+                        // `domains/meta.ts`): parsed as a URL path, without its
+                        // trailing slash. ⛔ Never `metaPath` — on the
+                        // environment-scoped mount that is the route TEMPLATE, and
+                        // the successor read `/environments/:environmentId/…/layers`,
+                        // a path no client can request. The parse is what keeps the
+                        // path a valid URI reference: the Hono adapter hands over a
+                        // `decodeURI`'d path (`lead%20all` arrives as `lead all`),
+                        // and the parse percent-encodes it again. A request with no
+                        // path names no successor: `Deprecation` alone, as the
+                        // helper prescribes for a transport that cannot say where
+                        // it serves the item.
                         const wantLayered = metaReadGate.wantsMetaItemLayers(req.query);
                         if (wantLayered && typeof (p as any).getMetaItemLayered === 'function') {
+                            const requestPath: unknown = req.path;
                             const deprecation = metaReadGate.metaItemLayersDeprecationHeaders(
-                                `${metaPath}/${req.params.type}/${req.params.name}`,
+                                typeof requestPath === 'string' && requestPath.startsWith('/')
+                                    ? new URL(`http://rest-server.invalid${requestPath}`).pathname.replace(/\/+$/, '') || undefined
+                                    : undefined,
                             );
                             for (const [header, value] of Object.entries(deprecation)) res.header(header, value);
                             await this.serveMetaItemLayered(req, res, environmentId, p, maskPosture);