fix(spec): five exported symbols resolved to any — type the recursive schemas and gate it in CI (#4171) (#4194)

A recursive Zod schema needs an explicit annotation to break its circular
inference, and five of them took the cheapest one available:

    export const NavigationItemSchema: z.ZodType<any> = z.lazy(() => …);
    export type NavigationItem = z.infer<typeof NavigationItemSchema>;   // → any

It compiles, it validates correctly at runtime, and it silently throws the type
away. `NavigationItem`, `FormField`, `JoinNode` and `NormalizedFilter` were all
`any` on the published surface, plus `FieldNodeSchema` — which had no exported
type alias yet, so `z.infer<typeof FieldNodeSchema>` was `any` and
`QueryAST['fields']` with it.

That is worse than a missing export. #4115 tells every consumer that a local
declaration under a spec export's name must be replaced by a binding to the
spec — and for these, obeying it replaced a precise type with `any`. It is hard
to catch by inspection because `any` is mutually assignable with everything, so
the natural "are these the same type?" check answers yes in both directions and
recommends precisely the wrong action — the same failure family as #4075's
`[key: string]: any` on `ActionDef`.

Now annotated with the real type, using the pattern `QueryAST` already follows
in `data/query.zod.ts`: infer the non-recursive part, tie the recursive knot in
the type, so the keys stay derived from the schema. Runtime validation is
unchanged — every schema parses exactly what it parsed before.

What the types immediately caught, none of it visible while they were `any`:

- `account.app.ts` set `defaultOpen` on three nav groups, a key the spec has
  never declared; it worked only because objectui's NavigationRenderer still
  falls back to that legacy alias. Fixed at the producer per Prime Directive
  #12 — the canonical key is `expanded`.
- The MongoDB driver built its projection with `projection[field] = 1` over
  `query.fields`, so a relationship `FieldNode` would have keyed the projection
  on `"[object Object]"`. It now reads the node's field name.
- `setup.app.ts`, `studio.app.ts` and `setup-nav.contributions.ts` are annotated
  with the PARSED `App` / `NavigationContribution` types but omitted
  `.default()`ed keys (`expanded`, `target`), as did the form fields
  `metadata-protocol` synthesizes for `getUiView` (`span`). Each now states the
  default it was relying on, matching what the surrounding literals already do
  for `active` / `isDefault` / `collapsible` / `collapsed` / `columns`.

Gated, not just fixed (`check:exported-any`, wired into the required TypeScript
Type Check job). `api-surface.json` records that an export exists and never what
it resolves to, which is how these survived a whole major with every gate green.
The new scan reads the built `.d.ts` a consumer's import actually resolves to
and fails on any exported type that resolves to `any` — or any exported schema
whose output is `any`, the root cause, and the only reason `FieldNodeSchema` was
visible at all. Its `KNOWN_ANY` ledger is shrink-only and currently empty. It
self-tests against the real zod first, so if the internals it reads are ever
renamed the gate fails loudly instead of quietly passing everything forever.


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

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

Author: os-zhuang

.changeset/exported-types-no-longer-resolve-to-any.md

@@ -0,0 +1,84 @@
+---
+"@objectstack/spec": minor
+"@objectstack/platform-objects": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/driver-mongodb": patch
+---
+
+fix(spec): five exported symbols resolved to `any` — type the recursive schemas and gate it in CI (#4171)
+
+A recursive Zod schema needs an explicit annotation to break its circular
+inference, and five of them took the cheapest one available:
+
+```ts
+export const NavigationItemSchema: z.ZodType<any> = z.lazy(() => …);
+export type NavigationItem = z.infer<typeof NavigationItemSchema>;   // → any
+```
+
+It compiles, it validates correctly at runtime, and it silently throws the type
+away. `NavigationItem`, `FormField`, `JoinNode` and `NormalizedFilter` were all
+`any` on the published surface, plus `FieldNodeSchema` — which had no exported
+type alias yet, so `z.infer<typeof FieldNodeSchema>` was `any` and
+`QueryAST['fields']` with it.
+
+That is worse than a missing export. #4115 tells every consumer that a local
+declaration under a spec export's name must be replaced by a binding to the
+spec — and for these, obeying it **replaced a precise type with `any`**.
+objectui's `NavigationItem` is a 118-line documented interface (`recordId`
+template variables, `requiresObject` / `requiresService` capability gates,
+`filters` precedence); every key of it exists in the spec's version, so by every
+available signal it read as a redundant fork safe to delete. Deleting it swapped
+a fully-typed interface for `any`, with no compile error anywhere to say so.
+
+It is hard to catch by inspection because `any` is mutually assignable with
+everything, so the natural "are these the same type?" check answers *yes* in both
+directions and recommends precisely the wrong action. Same failure family as
+#4075's `[key: string]: any` on `ActionDef`: a type that agrees with everything
+reads as agreement.
+
+**Now annotated with the real type**, using the pattern `QueryAST` already
+follows in `data/query.zod.ts` — infer the non-recursive part, tie the recursive
+knot in the type, so the keys stay derived from the schema instead of being
+hand-maintained beside it:
+
+```ts
+const BaseXSchema = z.object({ …every non-recursive key });
+export type X = z.infer<typeof BaseXSchema> & { children?: X[] };
+export const XSchema: z.ZodType<X> = z.lazy(() => BaseXSchema.extend({
+  children: z.array(XSchema).optional(),
+}));
+```
+
+`z.infer` now resolves to the type it should always have been: `NavigationItem`
+is the nine-branch discriminated union, `FormField` the 30-key form-field
+contract (with `visibleOn` absent by construction — ADR-0089 D2 folds it into
+`visibleWhen` at the boundary), `JoinNode` and the newly exported `FieldNode`
+the query AST nodes, `NormalizedFilter` the normalized filter AST. Runtime
+validation is unchanged: every schema parses exactly what it parsed before.
+
+**What the types immediately caught**, none of it visible while they were `any`:
+
+- `account.app.ts` set `defaultOpen` on three nav groups — a key the spec has
+  never declared. It worked only because objectui's `NavigationRenderer` still
+  falls back to that legacy alias. Fixed at the producer per Prime Directive
+  #12: the canonical key is `expanded`.
+- The MongoDB driver built its projection with `projection[field] = 1` over
+  `query.fields`, so a relationship `FieldNode` would have keyed the projection
+  on `"[object Object]"`. It now reads the node's field name.
+- `setup.app.ts`, `studio.app.ts` and `setup-nav.contributions.ts` are annotated
+  with the PARSED `App` / `NavigationContribution` types but omitted
+  `.default()`ed keys (`expanded`, `target`), as did the form fields
+  `metadata-protocol` synthesizes for `getUiView` (`span`). Each now states the
+  default it was relying on, matching what the surrounding literals already do
+  for `active` / `isDefault` / `collapsible` / `collapsed` / `columns`.
+
+**Gated, not just fixed** (`check:exported-any`, wired into the required
+`TypeScript Type Check` job). `api-surface.json` records that an export *exists*
+and never what it *resolves to*, which is how these survived a whole major with
+every gate green. The new scan reads the built `.d.ts` a consumer's import
+actually resolves to and fails on any exported type that resolves to `any` — or
+any exported schema whose output is `any`, the root cause, and the only reason
+`FieldNodeSchema` was visible at all. Its `KNOWN_ANY` ledger is shrink-only and
+currently empty. It self-tests against the real zod first, so if the internals it
+reads are ever renamed the gate fails loudly instead of quietly passing
+everything forever.

.github/workflows/lint.yml

@@ -284,6 +284,19 @@ jobs:
       - name: Check @objectstack/spec public API surface
         run: pnpm --filter @objectstack/spec run check:api-surface
 
+      # Same surface, the other axis: api-surface.json records that an export
+      # EXISTS, never what it resolves to — so four exported types sat at `any`
+      # across a whole major with every gate green (#4171). #4115 tells consumers
+      # to replace a local declaration with the spec import, which for those four
+      # traded a precise type for one that constrains nothing, silently: `any` is
+      # mutually assignable with everything, so the check that would catch the
+      # swap reports "identical, safe to re-export". Reads the built dist a
+      # consumer's import actually resolves to, so it runs after the build step
+      # with the other consumer gates. Self-tests first — a scan whose green
+      # result is "nothing found" has to prove it can still find something.
+      - name: Check no exported spec type resolves to `any`
+        run: pnpm --filter @objectstack/spec run check:exported-any
+
       # Anti-drift for the skill EXAMPLES, not just the skill reference indexes
       # (#3094). The TypeScript in skills/ is the first thing an AI copies when
       # authoring metadata, yet nothing type-checked it — so it rotted silently

AGENTS.md

@@ -274,10 +274,20 @@ believe it, and before you file a bug about `main` being red. (Two phantom "brea
 removals" this way while writing this section; `check:generated` now prints this caveat
 inline when that gate is the one failing.)
 
-`check:liveness`, `check:empty-state`, `check:skill-examples` and
-`check:react-conformance` are pure checks with no generator — a failure there is a real
-finding to fix, not an artifact to regenerate. `check:generated` names them as
-deliberately not run, so its "all up to date" never reads as "everything passed".
+`check:liveness`, `check:empty-state`, `check:skill-examples`,
+`check:react-conformance` and `check:exported-any` are pure checks with no generator — a
+failure there is a real finding to fix, not an artifact to regenerate. `check:generated`
+names them as deliberately not run, so its "all up to date" never reads as "everything
+passed".
+
+`check:exported-any` is the one of those that also reads the built `dist/*.d.ts`, so the
+stale-`dist` caveat above applies to it too. It asks the other half of the
+`api-surface.json` question: that snapshot records an export *exists*, never what it
+*resolves to*, which is how five exported symbols sat at `any` for a whole major with
+every gate green (#4171). A recursive Zod schema needs an annotation to break its
+circular inference, and `z.ZodType<any>` compiles, validates correctly, and silently
+throws the type away — annotate with the type instead (`QueryAST` in
+`src/data/query.zod.ts` is the pattern).
 
 Two generators have **no** gate at all — `gen:openapi` and `gen:sbom`. Nothing verifies
 their output is current; the script reports that each run rather than staying silent

content/docs/references/ui/view.mdx

@@ -158,12 +158,12 @@ Column footer summary configuration
 | **span** | `Enum<'auto' \| 'full'>` | optional | Relative field width. 'auto' (default — omit it): the renderer sizes the field from its widget type × the current column count (wide widgets like textarea/richtext/json/file/subform take the whole row). 'full': whole row at any column count. Prefer this over the absolute `colSpan`. |
 | **widget** | `string` | optional | Custom widget/component name (overrides type-based inference) |
 | **language** | `string` | optional | Code editor language (for type=code) |
-| **fields** | `[FormField](#formfield)[]` | optional | Sub-fields for composite/repeater/record types |
 | **keyField** | `{ field?: string; label?: string; placeholder?: string; helpText?: string; … }` | optional | Key column config for record-typed fields |
 | **dependsOn** | `string` | optional | Parent field name for cascading |
 | **visibleWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | Visibility predicate (CEL) — field shown only when TRUE. Root: `record`+`current_user` (runtime forms) or `data` (metadata forms). e.g. P`record.priority == 'urgent'` |
 | **visibleOn** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | [DEPRECATED → `visibleWhen`] Visibility predicate (CEL). Normalized to `visibleWhen` at parse. |
 | **disclosure** | `Enum<'inline' \| 'popover'>` | optional | Composite rendering: inline bordered box (default) or a summary line + gear popover (progressive disclosure). |
+| **fields** | `[FormField](#formfield)[]` | optional | Sub-fields for composite/repeater/record types |
 
 
 ---

packages/metadata-protocol/src/protocol.ts

@@ -2894,7 +2894,14 @@ export class ObjectStackProtocolImplementation implements
                     readonly: fields[f]?.readonly,
                     type: fields[f]?.type,
                     // Default to 2 columns for most, 1 for textareas
-                    colSpan: (fields[f]?.type === 'textarea' || fields[f]?.type === 'html') ? 2 : 1
+                    colSpan: (fields[f]?.type === 'textarea' || fields[f]?.type === 'html') ? 2 : 1,
+                    // `FormField.span` defaults to 'auto'; this view is hand-built
+                    // rather than run through `FormFieldSchema.parse()`, so the
+                    // default is spelled out to make the returned object a real
+                    // parsed `View` (the same reason the section below states its
+                    // own `collapsible` / `collapsed` / `columns` defaults). Was
+                    // unnoticed while `FormField` resolved to `any` (#4171).
+                    span: 'auto' as const
                 }));
 
              return {

packages/platform-objects/src/apps/account.app.ts

@@ -54,6 +54,13 @@ export const ACCOUNT_APP: App = {
   // No `requiredPermissions`: any authenticated user must be able to
   // manage their own linked accounts / personal OAuth apps. RLS on each
   // object scopes rows to the caller.
+  //
+  // Group open-state is `expanded` — the spec key. These entries said
+  // `defaultOpen`, objectui's legacy alias, which the spec has never declared
+  // and `.strict()` would reject; it worked only because objectui's
+  // NavigationRenderer still falls back to it, and because `NavigationItem`
+  // resolved to `any` so nothing checked the key here (#4171). Per Prime
+  // Directive #12 the producer is the place to fix that, not the renderer.
   navigation: [
     // Profile is the canonical landing — a hand-written React settings card
     // (Vercel/Linear style) registered in the Console SPA as

packages/platform-objects/src/apps/setup-nav.contributions.ts

@@ -26,6 +26,11 @@ import type { NavigationContribution } from '@objectstack/spec/ui';
 
 const BASE_PRIORITY = 100;
 
+// `target: '_self'` on every `url` entry is the schema's own default, spelled
+// out: this array is annotated with the PARSED type, where a `.default()`ed key
+// is required. Omitting it was only possible while `NavigationItem` resolved to
+// `any` and nothing checked these literals at all (#4171).
+
 // Marketplace entries (browse / installed) moved to
 // @objectstack/cloud-connection's marketplace plugins (cloud ADR-0009:
 // the nav lives and dies with the capability — no plugin, no entry).
@@ -97,7 +102,7 @@ export const SETUP_NAV_CONTRIBUTIONS: NavigationContribution[] = [
     group: 'group_configuration',
     priority: BASE_PRIORITY,
     items: [
-      { id: 'nav_settings_hub', type: 'url', label: 'All Settings', url: '/apps/setup/system/settings', icon: 'settings-2', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_hub', type: 'url', target: '_self', label: 'All Settings', url: '/apps/setup/system/settings', icon: 'settings-2', requiredPermissions: ['manage_platform_settings'] },
       // Workspace identity first — Localization (order 2) and Company (order 3)
       // are the lowest-`order` settings manifests and the first thing a new
       // company admin configures. They ship as `service-settings` manifests
@@ -106,15 +111,15 @@ export const SETUP_NAV_CONTRIBUTIONS: NavigationContribution[] = [
       // admin consoles (Salesforce "Company Information", ServiceNow) surface
       // both directly. No `requiredPermissions` — matches Branding (read perm is
       // the app's base `setup.access`).
-      { id: 'nav_settings_localization', type: 'url', label: 'Localization', url: '/apps/setup/system/settings/localization', icon: 'globe' },
-      { id: 'nav_settings_company', type: 'url', label: 'Company', url: '/apps/setup/system/settings/company', icon: 'building-2' },
-      { id: 'nav_settings_branding', type: 'url', label: 'Branding', url: '/apps/setup/system/settings/branding', icon: 'palette' },
-      { id: 'nav_settings_auth', type: 'url', label: 'Authentication', url: '/apps/setup/system/settings/auth', icon: 'lock-keyhole', requiredPermissions: ['manage_platform_settings'] },
-      { id: 'nav_settings_mail', type: 'url', label: 'Email', url: '/apps/setup/system/settings/mail', icon: 'mail', requiredPermissions: ['manage_platform_settings'] },
-      { id: 'nav_settings_storage', type: 'url', label: 'File Storage', url: '/apps/setup/system/settings/storage', icon: 'hard-drive', requiredPermissions: ['manage_platform_settings'] },
-      { id: 'nav_settings_ai', type: 'url', label: 'AI & Embedder', url: '/apps/setup/system/settings/ai', icon: 'sparkles', requiredPermissions: ['manage_platform_settings'] },
-      { id: 'nav_settings_knowledge', type: 'url', label: 'Knowledge', url: '/apps/setup/system/settings/knowledge', icon: 'book-open', requiredPermissions: ['manage_platform_settings'] },
-      { id: 'nav_settings_feature_flags', type: 'url', label: 'Feature Flags', url: '/apps/setup/system/settings/feature_flags', icon: 'flag' },
+      { id: 'nav_settings_localization', type: 'url', target: '_self', label: 'Localization', url: '/apps/setup/system/settings/localization', icon: 'globe' },
+      { id: 'nav_settings_company', type: 'url', target: '_self', label: 'Company', url: '/apps/setup/system/settings/company', icon: 'building-2' },
+      { id: 'nav_settings_branding', type: 'url', target: '_self', label: 'Branding', url: '/apps/setup/system/settings/branding', icon: 'palette' },
+      { id: 'nav_settings_auth', type: 'url', target: '_self', label: 'Authentication', url: '/apps/setup/system/settings/auth', icon: 'lock-keyhole', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_mail', type: 'url', target: '_self', label: 'Email', url: '/apps/setup/system/settings/mail', icon: 'mail', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_storage', type: 'url', target: '_self', label: 'File Storage', url: '/apps/setup/system/settings/storage', icon: 'hard-drive', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_ai', type: 'url', target: '_self', label: 'AI & Embedder', url: '/apps/setup/system/settings/ai', icon: 'sparkles', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_knowledge', type: 'url', target: '_self', label: 'Knowledge', url: '/apps/setup/system/settings/knowledge', icon: 'book-open', requiredPermissions: ['manage_platform_settings'] },
+      { id: 'nav_settings_feature_flags', type: 'url', target: '_self', label: 'Feature Flags', url: '/apps/setup/system/settings/feature_flags', icon: 'flag' },
     ],
   },
   {

packages/platform-objects/src/apps/setup.app.ts

@@ -47,12 +47,18 @@ export const SETUP_APP: App = {
   requiredPermissions: ['setup.access'],
   // Shell only — the stable group anchors. Children are supplied by
   // `navigationContributions` from the packages that own the objects.
+  //
+  // `expanded: false` is the schema's own default, spelled out: this literal is
+  // annotated with the PARSED `App` type, where a `.default()`ed key is
+  // required. Omitting it was only possible while `NavigationItem` resolved to
+  // `any` and nothing checked these entries at all (#4171).
   navigation: [
     {
       id: 'group_overview',
       type: 'group',
       label: 'Overview',
       icon: 'layout-dashboard',
+      expanded: false,
       requiredPermissions: ['manage_platform_settings'],
       children: [],
     },
@@ -61,27 +67,31 @@ export const SETUP_APP: App = {
       type: 'group',
       label: 'Apps',
       icon: 'package',
+      expanded: false,
       children: [],
     },
     {
       id: 'group_people_org',
       type: 'group',
       label: 'People & Organization',
       icon: 'users',
+      expanded: false,
       children: [],
     },
     {
       id: 'group_access_control',
       type: 'group',
       label: 'Access Control',
       icon: 'shield',
+      expanded: false,
       children: [],
     },
     {
       id: 'group_approvals',
       type: 'group',
       label: 'Approvals',
       icon: 'check-circle',
+      expanded: false,
       requiredPermissions: ['manage_platform_settings'],
       children: [],
     },
@@ -90,13 +100,15 @@ export const SETUP_APP: App = {
       type: 'group',
       label: 'Configuration',
       icon: 'sliders-horizontal',
+      expanded: false,
       children: [],
     },
     {
       id: 'group_diagnostics',
       type: 'group',
       label: 'Diagnostics',
       icon: 'stethoscope',
+      expanded: false,
       requiredPermissions: ['manage_platform_settings'],
       children: [],
     },
@@ -105,6 +117,7 @@ export const SETUP_APP: App = {
       type: 'group',
       label: 'Integrations',
       icon: 'plug',
+      expanded: false,
       requiredPermissions: ['manage_platform_settings'],
       children: [],
     },