refactor(rest): compile the non-door getMetaItems request literals against the declared contract (#9805) (#9845)

Nine getMetaItems call sites in packages/rest/src/rest-server.ts outside the
four meta-read doors passed their request through `as any` (or through a
`p: any` parameter), so the compiler checked nothing about them. Every member
they thread has been expressible in declared types since #9741 landed
`previewDrafts` on GetMetaItemsRequest and the TransportScopedMetaRequest
envelope for the transport-level environmentId.

Each literal is now a named const typed TransportScopedMetaRequest of
GetMetaItemsRequest (or plain GetMetaItemsRequest where the site threads no
environmentId), the same shape #9741 gave the doors.

No behaviour change: the outgoing payloads are byte-identical (same keys, same
conditional spreads). The optional-call spelling, the typeof-function guards
and the runtime-shaped result handling all deliberately survive — retiring any
of them would change behaviour rather than typing — and the envelope alias now
documents why.


Claude-Session: https://claude.ai/code/session_01WeN7F6jQFpcqW2BN56RdPa

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

Author: huangyiirene

.changeset/getmetaitems-helper-request-literals-typed.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/rest": patch
+---
+
+refactor(rest): the non-door `getMetaItems` request literals are compiled against the declared contract (#9805)
+
+Nine `getMetaItems` call sites in `packages/rest/src/rest-server.ts` outside the
+four meta-read doors still passed their request through `as any` (or through a
+`p: any` parameter), so the compiler checked nothing about them. Every member
+they thread has been expressible in declared types since #9741 landed
+`previewDrafts` on `GetMetaItemsRequest` and the `TransportScopedMetaRequest`
+envelope for the transport-level `environmentId` — the casts were pure
+blindness, and an un-typed request literal is exactly the class that lets a
+future key drift silently.
+
+Each literal is now a named const typed
+`TransportScopedMetaRequest<GetMetaItemsRequest>` (or plain
+`GetMetaItemsRequest` where the site threads no `environmentId`), the same shape
+#9741 gave the doors: the object-metadata read behind the API-exposure gate, the
+audience book fetch, the book-tree book and doc listings, the doc corpus behind
+the audience resolver, the public-form view lookup, the public-form object
+schema, the public-lookup reference resolution, and the dataset listing.
+
+**No behaviour change of any kind, and nothing about the wire moves.** The
+outgoing payloads are byte-identical (same keys, same conditional spreads); the
+edit hoists each literal into a const and drops a type-level cast. Two spellings
+at these sites deliberately SURVIVE, because retiring either would change
+behaviour rather than typing, and both are now documented on the envelope alias:
+
+- the optional call (`getMetaItems?.(…)`) and the `typeof … === 'function'`
+  guards — `getMetaItems` is a required `MetadataProtocol` member, so these are
+  not feature detection in the type sense, but a host may occupy the protocol
+  slot with an object that does not implement the whole surface (the reason
+  `metaTypeIsLive` documents the same spelling for `getMetaTypes`). Retiring one
+  turns a tolerated absence into a `TypeError`;
+- the result handling — the verb is declared to return `{ type, items }` while
+  these sites also tolerate the bare-array shape older hosts and stubs return,
+  so the response stays runtime-shaped on purpose.
+
+Genuinely feature-detected server-only verbs (`getMetaDiagnostics`,
+`listDrafts`, `migrateStoredMetadata`, …) are untouched — runtime casts are the
+documented convention there, and tightening one would turn optional capability
+detection into a hard dependency.

packages/rest/src/rest-server.ts

@@ -134,6 +134,28 @@ export type RestProtocol = DataProtocol & MetadataProtocol;
  * is now checked against the spec contract — an undeclared member is a compile
  * error at the call site, not a cast-and-hope. Never add protocol members
  * here; a key that belongs to the request belongs in the spec schema.
+ *
+ * [#9805] The same typing now covers the NON-door `getMetaItems` helper call
+ * sites in this file (the object, book, doc, view and dataset listings). Two
+ * spellings those sites carry deliberately SURVIVE the tightening, because
+ * retiring either would change behaviour rather than typing:
+ *
+ *   - The OPTIONAL CALL (`getMetaItems?.(…)`) and the
+ *     `typeof … === 'function'` guards. `getMetaItems` is a REQUIRED
+ *     `MetadataProtocol` member, so these are not feature detection in the
+ *     type sense — but a host may occupy the protocol slot with an object
+ *     that does not implement the whole surface, which is the measured reason
+ *     they exist (`metaTypeIsLive` documents the same deliberate spelling for
+ *     `getMetaTypes`). Retiring one turns a tolerated absence into a
+ *     `TypeError`.
+ *   - The RESULT handling. `getMetaItems` is declared to return
+ *     `{ type, items }`, while these sites also tolerate the bare-array shape
+ *     older hosts and stubs return (see `metaItemsArray`), so the response
+ *     stays runtime-shaped on purpose.
+ *
+ * The REQUEST is what is fully typeable today, and the request is what is
+ * typed — which is the whole point: an undeclared key in one of these
+ * literals is now a compile error instead of a cast-and-hope.
  */
 type TransportScopedMetaRequest<R> = R & { environmentId?: string };
 import {
@@ -1329,10 +1351,11 @@ export class RestServer {
      */
     private async loadObjectItems(p: RestProtocol, environmentId: string | undefined): Promise<any[]> {
         try {
-            const r: any = await (p as any).getMetaItems?.({
+            const objectsRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                 type: 'object',
                 ...(environmentId ? { environmentId } : {}),
-            });
+            };
+            const r: any = await p.getMetaItems?.(objectsRequest);
             return Array.isArray(r?.items) ? r.items : Array.isArray(r) ? r : [];
         } catch (err) {
             // [#3545] The API-exposure gate fails OPEN when object metadata can't
@@ -1711,11 +1734,12 @@ export class RestServer {
     }
 
     /** Fetch every book of the environment, shaped for the audience resolver. */
-    private async fetchAudienceBooks(p: any, environmentId: string | undefined): Promise<any[]> {
-        const raw = await p.getMetaItems({
+    private async fetchAudienceBooks(p: RestProtocol, environmentId: string | undefined): Promise<any[]> {
+        const booksRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
             type: 'book',
             ...(environmentId ? { environmentId } : {}),
-        } as any).catch(() => []);
+        };
+        const raw = await p.getMetaItems(booksRequest).catch(() => []);
         return RestServer.metaItemsArray(raw).map((b: any) =>
             b && typeof b === 'object' ? { ...b, packageId: b._packageId } : b,
         );
@@ -4554,11 +4578,12 @@ export class RestServer {
                         const norm = (raw: any): any[] =>
                             Array.isArray(raw) ? raw : (raw && Array.isArray(raw.items) ? raw.items : []);
 
-                        const books = norm(await prot.getMetaItems({
+                        const booksRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                             type: 'book',
                             ...(packageId ? { packageId } : {}),
                             ...(environmentId ? { environmentId } : {}),
-                        } as any));
+                        };
+                        const books = norm(await prot.getMetaItems(booksRequest));
                         let book = books.find((b: any) => b && b.name === req.params.name);
                         if (!book) {
                             // Unknown name → the implicit per-package book (§6.4).
@@ -4583,11 +4608,12 @@ export class RestServer {
                             return;
                         }
 
-                        const docs = norm(await prot.getMetaItems({
+                        const docsRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                             type: 'doc',
                             ...(packageId ? { packageId } : {}),
                             ...(environmentId ? { environmentId } : {}),
-                        } as any))
+                        };
+                        const docs = norm(await prot.getMetaItems(docsRequest))
                             .map((d: any) => (d && typeof d === 'object' ? resolveDocLocale(d, locale) : d))
                             .map((d: any) => ({
                                 name: d.name,
@@ -5135,10 +5161,12 @@ export class RestServer {
                                     if (caller.authenticated && !RestServer.anyPermissionSetAudience(books)) {
                                         allowed = true; // no gated book anywhere → org suffices
                                     } else {
-                                        const corpus = RestServer.metaItemsArray(await p.getMetaItems({
+                                        const docCorpusRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                                             type: 'doc',
                                             ...(environmentId ? { environmentId } : {}),
-                                        } as any).catch(() => []))
+                                        };
+                                        const corpus = RestServer.metaItemsArray(
+                                            await p.getMetaItems(docCorpusRequest).catch(() => []))
                                             .filter((d: any) => d && typeof d === 'object')
                                             .map((d: any) => ({
                                                 name: d.name,
@@ -8028,10 +8056,11 @@ export class RestServer {
         ): Promise<{ view: any; form: any; object: string } | null> => {
             const p = await this.resolveProtocol(environmentId, req);
             if (typeof (p as any).getMetaItems !== 'function') return null;
-            const result: any = await (p as any).getMetaItems({
+            const viewsRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                 type: 'view',
                 ...(environmentId ? { environmentId } : {}),
-            });
+            };
+            const result: any = await p.getMetaItems(viewsRequest);
             const items: any[] = Array.isArray(result?.items)
                 ? result.items
                 : Array.isArray(result)
@@ -8092,10 +8121,11 @@ export class RestServer {
                     try {
                         const p = await this.resolveProtocol(environmentId, req);
                         if (typeof (p as any).getMetaItems === 'function') {
-                            const r: any = await (p as any).getMetaItems({
+                            const objectsRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                                 type: 'object',
                                 ...(environmentId ? { environmentId } : {}),
-                            });
+                            };
+                            const r: any = await p.getMetaItems(objectsRequest);
                             const items: any[] = Array.isArray(r?.items) ? r.items : Array.isArray(r) ? r : [];
                             const obj = items.find((o: any) => o?.name === match.object);
                             if (obj && obj.fields && typeof obj.fields === 'object') {
@@ -8408,10 +8438,11 @@ export class RestServer {
                     let referenceTo: string | undefined = picker.object;
                     if (!referenceTo && typeof (p as any).getMetaItems === 'function') {
                         try {
-                            const r: any = await (p as any).getMetaItems({
+                            const objectsRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                                 type: 'object',
                                 ...(environmentId ? { environmentId } : {}),
-                            });
+                            };
+                            const r: any = await p.getMetaItems(objectsRequest);
                             const items: any[] = Array.isArray(r?.items) ? r.items : Array.isArray(r) ? r : [];
                             const obj = items.find((o: any) => o?.name === match.object);
                             const def = obj?.fields?.[fieldName];
@@ -8611,7 +8642,8 @@ export class RestServer {
                     let dataset = body.dataset;
                     if (!dataset && body.datasetName) {
                         const p = await this.resolveProtocol(environmentId, req);
-                        const items = await (p as any).getMetaItems?.({ type: 'dataset', previewDrafts }).catch(() => null);
+                        const datasetRequest: GetMetaItemsRequest = { type: 'dataset', previewDrafts };
+                        const items: any = await p.getMetaItems?.(datasetRequest).catch(() => null);
                         const list = Array.isArray(items?.items) ? items.items : (Array.isArray(items) ? items : []);
                         dataset = list.find((d: any) => d?.name === body.datasetName);
                         if (!dataset) {