feat(spec): declare previewDrafts/state on meta-read requests; record environmentId as transport-level; retire REST door casts (#9741) (#9804)

* feat(spec): declare previewDrafts/state draft-visibility switches on meta-read requests; record environmentId as transport-level (#9741)

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

* chore: regen protocol docs; changeset (#9741)

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

---------

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

Author: os-elon

.changeset/preview-drafts-state-declared.md

@@ -0,0 +1,6 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": patch
+---
+
+Declare the draft-visibility switches on the meta-read request schemas, exactly where the implementation enforces them (#9741, maintainer ruling 2026-08-18): `GetMetaItemsRequestSchema` gains `previewDrafts?: boolean`, and `GetMetaItemRequestSchema` gains `state?: 'active' | 'draft'` plus `previewDrafts?: boolean`. Both members are draft-visibility switches only — declaration ≠ authorization: ADR-0106 masking is unaffected, and draft access stays admin-gated upstream. The cached and layered read requests deliberately declare neither (their implementations enforce neither). `environmentId` stays OUT of the protocol request shape by explicit ruling — it is the transport-level multi-kernel routing key, recorded schema-side as a decision rather than an omission. The REST meta-read doors (list, cached and uncached single-item, layered) drop their `as any` request casts: each request literal now compiles against the declared spec shape, with the transport-level `environmentId` carried by a typed transport envelope (`TransportScopedMetaRequest`) instead of a cast. Accept-set widening catch-up on the declared surface; zero runtime behaviour change.

content/docs/references/api/protocol.mdx

@@ -753,6 +753,8 @@ Enable package response
 | **name** | `string` | ✅ | Item name (snake_case identifier) |
 | **packageId** | `string` | optional | Optional package ID to filter items by |
 | **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization row is served as the item. Absent = environment-wide read: only env-level overlays apply and no org partition is consulted. |
+| **state** | `Enum<'active' \| 'draft'>` | optional | Draft-visibility switch — which lifecycle row to read (strict mode): `'draft'` opens the pending draft buffer (Studio's editor read) and fails when no draft exists; absent or `'active'` reads the live published row. Distinct from `previewDrafts`, which FALLS BACK to the active row when no draft exists. Declaration ≠ authorization: this member only selects which stored row is read — ADR-0106 masking is unaffected, and draft access is gated upstream, not by this schema. |
+| **previewDrafts** | `boolean` | optional | Draft-visibility switch (ADR-0033 draft-overlay preview, non-strict): when true and `state` is not `'draft'`, a pending draft row is preferred if one exists, else the read falls back to the active row — the render path degrades to the published value instead of erroring. A served draft is tagged `_draft: true` so UIs can badge it. Declaration ≠ authorization: this member only switches which row is read, and ADR-0106 masking is unaffected — draft preview is admin-gated upstream, not by this schema. |
 
 
 ---
@@ -789,6 +791,7 @@ Enable package response
 | **type** | `string` | ✅ | Metadata type name (e.g., "object", "plugin") |
 | **packageId** | `string` | optional | Optional package ID to filter items by |
 | **organizationId** | `string` | optional | Organization (tenant) scope for the read. Selects the org partition in the ADR-0005 overlay read order — org overlay wins over env-wide overlay wins over packaged artifact — so it decides which tenant's customization rows are merged into the list. Absent = environment-wide read: only env-level overlays apply and no org partition is consulted. |
+| **previewDrafts** | `boolean` | optional | Draft-visibility switch (ADR-0033 draft-overlay preview): when true, pending `state='draft'` rows are overlaid on the active list — draft wins on name collision, draft-only items appear, and each overlaid item is tagged `_draft: true` so UIs can badge the preview. Absent/false = published world only. Declaration ≠ authorization: this member only switches which rows are read, and ADR-0106 masking is unaffected — callers without draft-preview authorization are refused upstream (admin-gated), not by this schema. |
 
 
 ---

packages/rest/src/rest-server.ts

@@ -60,6 +60,15 @@ import { refuseUnknownQueryParams } from './query-allowlist.js';
 import type { DirectMountedRoute, MountedRouteSource } from './direct-mount.js';
 import { RestServerConfig, RestApiConfig, CrudEndpointsConfig, MetadataEndpointsConfig, BatchEndpointsConfig, RouteGenerationConfig } from '@objectstack/spec/api';
 import { DataProtocol, MetadataProtocol } from '@objectstack/spec/api';
+// [#9741] Declared request shapes for the meta-read doors below — imported so
+// each door's request literal is compiled against the spec contract instead of
+// being smuggled past it with `as any` (see `TransportScopedMetaRequest`).
+import type {
+    GetMetaItemsRequest,
+    GetMetaItemRequest,
+    GetMetaItemCachedRequest,
+    GetMetaItemLayeredRequest,
+} from '@objectstack/spec/api';
 // [#8073] The closed ADR-0112 error vocabulary, so the explain family's single
 // refusal emitter types its `code` parameter as the vocabulary rather than as
 // `string` — an invented code is a compile error at the call site instead of a
@@ -108,6 +117,25 @@ import { sendError as sendEnvelopeError } from '@objectstack/types';
  * widen this contract.
  */
 export type RestProtocol = DataProtocol & MetadataProtocol;
+
+/**
+ * [#9741] Typed TRANSPORT envelope for the meta-read doors.
+ *
+ * `environmentId` is the multi-kernel routing key, and it is OUT of the
+ * protocol request shape **by explicit maintainer decision** (ruling recorded
+ * 2026-08-18 on #9741): `resolveProtocol(environmentId)` selects the target
+ * kernel *before* the protocol call, and the implementation's parameter types
+ * (`@objectstack/metadata-protocol`) never read it off the request — the spec
+ * schemas (`protocol.zod.ts`) record the same exclusion schema-side. The doors
+ * here still spread it into the outgoing payload (long-standing wire shape,
+ * deliberately unchanged by the ruling), so this alias declares that one
+ * transport-level member on top of the declared request type. The point is
+ * what it makes the compiler do: every OTHER key in a door's request literal
+ * 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.
+ */
+type TransportScopedMetaRequest<R> = R & { environmentId?: string };
 import {
     buildFieldMetaMap,
     referenceFieldNames,
@@ -2566,13 +2594,19 @@ export class RestServer {
         const layeredOrganizationId = organizationIdForMetaRead(
             req.params.type, layeredCtx?.tenantId,
         );
-        const layered = await p.getMetaItemLayered({
+        // [#9741] This door never carried an `as any`, but `p: any` meant its
+        // request literal was never checked either — the same blind spot with
+        // a different spelling. Typing the literal (spec shape + the
+        // transport-level `environmentId`, see `TransportScopedMetaRequest`)
+        // makes an undeclared key a compile error here too.
+        const layeredRequest: TransportScopedMetaRequest<GetMetaItemLayeredRequest> = {
             type: req.params.type,
             name: req.params.name,
             ...(layeredPackageId ? { packageId: layeredPackageId } : {}),
             ...(environmentId ? { environmentId } : {}),
             ...(layeredOrganizationId ? { organizationId: layeredOrganizationId } : {}),
-        });
+        };
+        const layered = await p.getMetaItemLayered(layeredRequest);
         // [ADR-0106 D5(4)] The layered view is a schema-bearing exit —
         // `code`, `overlay` and `effective` are each a full object schema.
         // Both entry points (the canonical `/layers` path and the deprecated
@@ -3974,13 +4008,18 @@ export class RestServer {
                         const listOrganizationId = organizationIdForMetaRead(
                             req.params.type, listCtx?.tenantId,
                         );
-                        const items = await p.getMetaItems({
+                        // [#9741] Typed against the spec request shape plus the
+                        // transport-level `environmentId` — the `as any` this
+                        // literal used to carry is retired now that the spec
+                        // declares `previewDrafts` (and `organizationId`, #9726).
+                        const listRequest: TransportScopedMetaRequest<GetMetaItemsRequest> = {
                             type: req.params.type,
                             packageId,
                             ...(previewDrafts ? { previewDrafts: true } : {}),
                             ...(environmentId ? { environmentId } : {}),
                             ...(listOrganizationId ? { organizationId: listOrganizationId } : {}),
-                        } as any);
+                        };
+                        const items = await p.getMetaItems(listRequest);
 
                         // RBAC-filter app metadata for authenticated users so
                         // privileged apps (Studio, Setup, etc.) and gated nav
@@ -4826,7 +4865,14 @@ export class RestServer {
                             const cacheI18n = await this.resolveI18nService(environmentId, req);
                             const cacheLocale = this.extractLocale(req, cacheI18n);
 
-                            const result = await p.getMetaItemCached({
+                            // [#9741] Typed request — `as any` retired. The
+                            // cached read carries NO draft-visibility members
+                            // on purpose: this branch is unreachable when
+                            // `previewDrafts` / `?state=draft` are set (the
+                            // fork above bypasses the cache for both), and the
+                            // implementation's `getMetaItemCached` signature
+                            // declares neither.
+                            const cachedRequest: TransportScopedMetaRequest<GetMetaItemCachedRequest> = {
                                 type: req.params.type,
                                 name: req.params.name,
                                 cacheRequest,
@@ -4840,7 +4886,8 @@ export class RestServer {
                                 // enters the ETag there, so the validator states
                                 // the scope rather than inheriting it.
                                 ...(readOrganizationId ? { organizationId: readOrganizationId } : {}),
-                            } as any);
+                            };
+                            const result = await p.getMetaItemCached(cachedRequest);
 
                             if (result.notModified) {
                                 res.status(304).send();
@@ -4944,18 +4991,26 @@ export class RestServer {
                             const stateParam = typeof req.query?.state === 'string'
                                 ? req.query.state.toLowerCase()
                                 : undefined;
-                            const envelope = await p.getMetaItem({
+                            // [#9741] Typed against the spec request shape —
+                            // the `as any` this literal used to carry is
+                            // retired now that the spec declares `state` and
+                            // `previewDrafts` (and `organizationId`, #9726).
+                            // No transport envelope: this door does not thread
+                            // `environmentId` (the kernel was already resolved
+                            // above), so the plain declared shape suffices.
+                            const itemRequest: GetMetaItemRequest = {
                                 type: req.params.type,
                                 name: req.params.name,
                                 packageId,
-                                ...(stateParam === 'draft' ? { state: 'draft' } : {}),
+                                ...(stateParam === 'draft' ? { state: 'draft' as const } : {}),
                                 ...(previewDrafts ? { previewDrafts: true } : {}),
                                 // [#9454] The uncached arm — `dashboard`'s route
                                 // (`isDashboardType`), and every read the cache
                                 // exclusions divert here. Same hoisted scope as
                                 // the cached arm above, by construction.
                                 ...(readOrganizationId ? { organizationId: readOrganizationId } : {}),
-                            } as any) as Record<string, any>;
+                            };
+                            const envelope = await p.getMetaItem(itemRequest) as Record<string, any>;
 
                             // [#5563] `getMetaItem` answers the envelope
                             // `{ type, name, item, lock, … }`. Unwrap ONCE here;

packages/spec/authorable-surface/api.json

@@ -739,6 +739,8 @@
     "api/GetMetaItemRequest:name",
     "api/GetMetaItemRequest:organizationId",
     "api/GetMetaItemRequest:packageId",
+    "api/GetMetaItemRequest:previewDrafts",
+    "api/GetMetaItemRequest:state",
     "api/GetMetaItemRequest:type",
     "api/GetMetaItemResponse:deletable",
     "api/GetMetaItemResponse:editable",
@@ -755,6 +757,7 @@
     "api/GetMetaItemResponse:type",
     "api/GetMetaItemsRequest:organizationId",
     "api/GetMetaItemsRequest:packageId",
+    "api/GetMetaItemsRequest:previewDrafts",
     "api/GetMetaItemsRequest:type",
     "api/GetMetaItemsResponse:items",
     "api/GetMetaItemsResponse:type",

packages/spec/src/api/protocol.test.ts

@@ -1357,6 +1357,121 @@ describe('meta-read request schemas declare organizationId (#9726 — declared =
   });
 });
 
+describe('meta-read request schemas declare the draft-visibility switches (#9741 — declared = enforced)', () => {
+  // Maintainer ruling 2026-08-18 (#9741): declare `previewDrafts` / `state`
+  // exactly where the implementation enforces them, and record `environmentId`
+  // as transport-level — OUT of the request shape by decision. The
+  // implementation's inline parameter types are the measure:
+  //   getMetaItems:  { …, previewDrafts?: boolean }            — no `state`
+  //   getMetaItem:   { …, state?: 'active'|'draft', previewDrafts?: boolean }
+  //   getMetaItemCached / getMetaItemLayered: NEITHER member
+  // As in the #9726 block above, accept-pins assert the parsed VALUE: these are
+  // non-strict objects, so `success` alone is exactly the silent-strip state
+  // this card closes.
+  const previewCases = [
+    ['GetMetaItemsRequestSchema', GetMetaItemsRequestSchema, { type: 'object' }],
+    ['GetMetaItemRequestSchema', GetMetaItemRequestSchema, { type: 'view', name: 'account_list' }],
+  ] as const;
+
+  it.each(previewCases)('%s accepts previewDrafts and PRESERVES it through parse', (_n, schema, base) => {
+    const result = schema.safeParse({ ...base, previewDrafts: true });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect((result.data as { previewDrafts?: boolean }).previewDrafts).toBe(true);
+    }
+  });
+
+  it.each(previewCases)('%s keeps previewDrafts OPTIONAL — a published-world read stays valid', (_n, schema, base) => {
+    const result = schema.safeParse(base);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect('previewDrafts' in (result.data as object)).toBe(false);
+    }
+  });
+
+  it.each(previewCases)('%s rejects a non-boolean previewDrafts — a switch, not a bag', (_n, schema, base) => {
+    expect(schema.safeParse({ ...base, previewDrafts: 'true' }).success).toBe(false);
+    expect(schema.safeParse({ ...base, previewDrafts: 1 }).success).toBe(false);
+  });
+
+  it('GetMetaItemRequestSchema accepts state and PRESERVES it through parse', () => {
+    for (const state of ['active', 'draft'] as const) {
+      const result = GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect((result.data as { state?: string }).state).toBe(state);
+      }
+    }
+  });
+
+  it('GetMetaItemRequestSchema keeps state OPTIONAL and refuses values outside the vocabulary', () => {
+    const absent = GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list' });
+    expect(absent.success).toBe(true);
+    if (absent.success) {
+      expect('state' in (absent.data as object)).toBe(false);
+    }
+    // The lifecycle vocabulary is CLOSED: `archived` is not a read state.
+    expect(GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state: 'archived' }).success).toBe(false);
+    expect(GetMetaItemRequestSchema.safeParse({ type: 'view', name: 'account_list', state: true }).success).toBe(false);
+  });
+
+  it('getMetaItems declares NO state — the list verb has no strict-draft mode (mirror of the inline type)', () => {
+    // Non-strict schema: an undeclared key parses green but is STRIPPED.
+    // Stripping is the observable that the member is NOT declared.
+    const result = GetMetaItemsRequestSchema.safeParse({ type: 'object', state: 'draft' });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect('state' in (result.data as object)).toBe(false);
+    }
+  });
+
+  it('cached and layered reads declare NEITHER switch — declared only where enforced', () => {
+    const cases = [
+      [GetMetaItemCachedRequestSchema, { type: 'view', name: 'account_list' }],
+      [GetMetaItemLayeredRequestSchema, { type: 'view', name: 'account_list' }],
+    ] as const;
+    for (const [schema, base] of cases) {
+      const result = schema.safeParse({ ...base, previewDrafts: true, state: 'draft' });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect('previewDrafts' in (result.data as object)).toBe(false);
+        expect('state' in (result.data as object)).toBe(false);
+      }
+    }
+  });
+});
+
+describe('environmentId stays OUT of the meta-read request shape — by decision, not omission (#9741)', () => {
+  // Maintainer ruling 2026-08-18 (#9741): `environmentId` is the
+  // TRANSPORT-level multi-kernel routing key. The REST layer resolves the
+  // target kernel from it BEFORE the protocol call, the implementation's
+  // parameter types never read it off the request, and these schemas record
+  // the same exclusion. This pin is the regression guard for that decision:
+  // if someone declares the member, the parse below stops stripping it and
+  // this test names the ruling they are overturning.
+  const cases = [
+    ['GetMetaItemsRequestSchema', GetMetaItemsRequestSchema, { type: 'object' }],
+    ['GetMetaItemRequestSchema', GetMetaItemRequestSchema, { type: 'view', name: 'account_list' }],
+    ['GetMetaItemCachedRequestSchema', GetMetaItemCachedRequestSchema, { type: 'view', name: 'account_list' }],
+    ['GetMetaItemLayeredRequestSchema', GetMetaItemLayeredRequestSchema, { type: 'view', name: 'account_list' }],
+  ] as const;
+
+  it.each(cases)('%s does not declare environmentId — a carried value is stripped by parse', (_n, schema, base) => {
+    const result = schema.safeParse({ ...base, environmentId: 'env_alpha' });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect('environmentId' in (result.data as object)).toBe(false);
+    }
+  });
+
+  it.each(cases)('%s has no environmentId in its declared shape', (_n, schema) => {
+    // Shape-level twin of the strip-pin above: `.shape` enumerates exactly the
+    // DECLARED members, so this fails even if stripping semantics ever change.
+    const shape = (schema as unknown as { shape: Record<string, unknown> }).shape;
+    expect(Object.keys(shape)).not.toContain('environmentId');
+  });
+});
+
 describe('MetadataProtocol declares getMetaItemLayered (#9740)', () => {
   // Type-level pins (compiled by the spec test typecheck, the
   // translation-typegen.test.ts pattern). The member is an interface