fix(spec): app 表单摘掉八个已退役的墓碑键输入,#3786 对账门改判「真实可授权面」(#5280) (#5318)

`app.form.ts` 仍在给作者渲染八个 `retiredKey()` 墓碑键的输入控件 ——
`version` / `homePageId` / `objects` / `apis` / `sharing` / `embed` /
`mobileNavigation` / `aria`(issue 只点了后三个,全量扫出八个)。墓碑是
`z.never().optional()`,填进去不是静默丢弃,是整条 save 硬失败并抛出该键
的退役处方。八个控件全部移除,按套件惯例在原位留注释说明能力去向。

真正的价值在门这一侧:#3786 的对账断言用 `key ∈ shape` 判定「Zod 接受该
键」。在 `retiredKey()` 出现之前这两件事同义,之后不是了 —— 墓碑**按设计**
把键留在 walked shape 里(退役套件的 liveness 行正因为键还在才保留),于是
八个墓碑键对该断言永远为真,门绿着而作者拿到 422。

谓词收紧为「∈ shape 且不是墓碑」,双向都改:
- form-only 方向拆成两条独立断言,失败信息能分清「未声明→静默丢弃」与
  「墓碑→硬失败」,后者更响也更早;
- zod-only 方向把墓碑键排除出「必须提供或立 ledger」的集合 —— 墓碑键的唯一
  正确处置就是不提供。此前 `object.fields.conditionalRequired` 不被要求回填
  纯属被一条无关的 `subset` ledger 条目挡住,是运气不是设计;
- ledger 的 `omit`/`subset` 自检改用 authorable 键计数,避免墓碑撑住一条
  已失效的豁免。

检测器判 **schema 节点**(optional 内层是否 `z.never`),不匹配键名 —— 键名
清单本身就是 #3786 要消灭的手抄列表。这是 `build-schemas.ts` 里 JSON Schema
侧 `isRetired()`(`{ not: {} }`)的 zod 侧孪生。四条合成 schema 上的自检把
机制钉住(含 union 成员仍 live 时不算退役的安全方向),不依赖任何当期墓碑,
免得墓碑随版本退场后这条门悄悄变空转。

RED-first 实证:谓词收紧、表单未改时,`app` 那条用例红,恰好点名八个键;
摘掉输入后 41/41 绿。

表单输入变动会带走 i18n 抽取键,四个 metadata-forms bundle 按 merge 模式
重生成(纯删除 8 组);两个分区描述原文仍在宣传已退役能力(zh-CN 的
basics/navigation 甚至点名「版本」「首页」),按 bundle 值可手写的惯例一并
订正为真实语义。


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

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

Author: os-zhuang

.changeset/app-form-tombstone-controls.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/spec": patch
+"@objectstack/platform-objects": patch
+---
+
+fix(spec): stop offering retired `app` keys in the metadata form, and make the reconciliation gate see tombstones (#5280)
+
+The `app` authoring form rendered **eight** controls for keys `AppSchema` had
+already retired to `retiredKey()` tombstones in 17.0.0 — `version`, `homePageId`,
+`objects`, `apis`, `sharing`, `embed`, `mobileNavigation` and `aria`. A tombstone
+is `z.never().optional()`, so filling one of those controls did not lose the
+value quietly: it failed the **entire save** with the key's removal
+prescription. The controls are gone, each with a comment in place naming where
+the capability went (`manifest.version`; the first `navigation` item by `order`
+plus `isDefault`; `defineStack({ objects })`; `defineStack({ apis })`;
+`FormView.sharing` for both public access and embedding; the component that
+renders the DOM node for `aria`).
+
+Nothing about the contract changes — every one of these keys was already
+rejected at parse. What changes is that an author is no longer shown a control
+that can only produce a 422.
+
+**The reconciliation gate now judges the right thing.** #3786's
+`metadata-form-zod-reconciliation.test.ts` asked whether an offered key was
+`∈ shape`. That was the same question as "may the author write this" until
+`retiredKey()` existed: a tombstone **deliberately stays in the shape** so the
+removal can carry its own upgrade prescription, so every one of those eight keys
+read as "the Zod accepts it" and the gate stayed green over all of them. It now
+asserts `∈ shape` **and not a tombstone**, in both directions — a retired key
+may not be offered, and its absence needs no ledger entry to excuse it. The
+detector reads the schema node (`z.never()` under the optional wrapper), never a
+list of key names, mirroring `isRetired()` on the JSON-Schema side of
+`build-schemas.ts`. The next `retiredKey()` retirement that forgets a form now
+fails this test instead of reaching an author.
+
+Retiring an authorable key already required pruning its form input; that step is
+now enforced rather than remembered.

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -937,15 +937,15 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       },
       content: {
         label: "Content",
-        description: "Objects and APIs this app uses."
+        description: "Ambient assistant binding. Objects and endpoints are declared on the stack, not the app."
       },
       branding: {
         label: "Branding",
         description: "Theme colors and logo."
       },
       access_and_sharing: {
         label: "Access & sharing",
-        description: "Who can access this app and how it can be embedded."
+        description: "Who can access this app. Public access and embedding are per form view, not app-level."
       }
     },
     fields: {
@@ -959,9 +959,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       description: {
         label: "Description"
       },
-      version: {
-        label: "Version"
-      },
       icon: {
         label: "Icon",
         helpText: "Lucide icon name (e.g. \"users\", \"briefcase\")"
@@ -981,22 +978,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
         label: "Areas",
         helpText: "Group items into collapsible areas"
       },
-      homePageId: {
-        label: "Home Page Id",
-        helpText: "Landing page when app opens"
-      },
-      mobileNavigation: {
-        label: "Mobile Navigation",
-        helpText: "Bottom tab bar config for mobile"
-      },
-      objects: {
-        label: "Objects",
-        helpText: "Object names this app exposes"
-      },
-      apis: {
-        label: "Apis",
-        helpText: "API endpoint definitions"
-      },
       defaultAgent: {
         label: "Default Agent",
         helpText: "AI agent for the ambient assistant button"
@@ -1008,18 +989,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       requiredPermissions: {
         label: "Required Permissions",
         helpText: "Permissions needed to access this app"
-      },
-      sharing: {
-        label: "Sharing",
-        helpText: "Public/internal/restricted access control"
-      },
-      embed: {
-        label: "Embed",
-        helpText: "iFrame embed configuration"
-      },
-      aria: {
-        label: "Aria",
-        helpText: "Accessibility labels"
       }
     }
   },

packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts

@@ -937,15 +937,15 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       content: {
         label: "Contenido",
-        description: "Objetos y API que usa esta app."
+        description: "Asignación del asistente ambiental. Los objetos y endpoints se declaran en el stack, no en la app."
       },
       branding: {
         label: "Marca",
         description: "Colores de tema y logotipo."
       },
       access_and_sharing: {
         label: "Acceso y uso compartido",
-        description: "Quién puede acceder a esta app y cómo puede incrustarse."
+        description: "Quién puede acceder a esta app. El acceso público y la incrustación son por vista de formulario, no a nivel de app."
       }
     },
     fields: {
@@ -959,9 +959,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       description: {
         label: "Descripción"
       },
-      version: {
-        label: "Versión"
-      },
       icon: {
         label: "Icono",
         helpText: "Nombre de icono Lucide (p. ej. \"users\", \"briefcase\")"
@@ -981,22 +978,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "Áreas",
         helpText: "Agrupa elementos en áreas plegables"
       },
-      homePageId: {
-        label: "ID de página inicial",
-        helpText: "Página de inicio al abrir la app"
-      },
-      mobileNavigation: {
-        label: "Navegación móvil",
-        helpText: "Configuración de barra de pestañas inferior para móvil"
-      },
-      objects: {
-        label: "Permisos de objeto",
-        helpText: "Nombres de objeto que expone esta app"
-      },
-      apis: {
-        label: "API",
-        helpText: "Definiciones de endpoints API"
-      },
       defaultAgent: {
         label: "Agente predeterminado",
         helpText: "Agente de IA para el botón de asistente ambiental"
@@ -1008,18 +989,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       requiredPermissions: {
         label: "Permisos requeridos",
         helpText: "Permisos necesarios para acceder a esta app"
-      },
-      sharing: {
-        label: "Compartición",
-        helpText: "Control de acceso público/interno/restringido"
-      },
-      embed: {
-        label: "Incrustación",
-        helpText: "Configuración de incrustación iFrame"
-      },
-      aria: {
-        label: "Accesibilidad",
-        helpText: "Etiquetas de accesibilidad"
       }
     }
   },

packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts

@@ -937,15 +937,15 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       content: {
         label: "コンテンツ",
-        description: "このアプリが使用するオブジェクトと API。"
+        description: "アンビエントアシスタントの割り当て。オブジェクトとエンドポイントはアプリではなくスタックで宣言します。"
       },
       branding: {
         label: "ブランディング",
         description: "テーマカラーとロゴ。"
       },
       access_and_sharing: {
         label: "アクセスと共有",
-        description: "このアプリにアクセス可能なユーザーと埋め込み方法。"
+        description: "このアプリにアクセスできるユーザー。公開アクセスと埋め込みはアプリ単位ではなくフォームビュー単位です。"
       }
     },
     fields: {
@@ -959,9 +959,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       description: {
         label: "説明"
       },
-      version: {
-        label: "バージョン"
-      },
       icon: {
         label: "アイコン",
         helpText: "Lucide アイコン名（例: \"users\", \"briefcase\"）"
@@ -981,22 +978,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "領域",
         helpText: "項目を折りたたみ可能なエリアにグループ化"
       },
-      homePageId: {
-        label: "ホームページ ID",
-        helpText: "アプリ起動時のランディングページ"
-      },
-      mobileNavigation: {
-        label: "モバイルナビゲーション",
-        helpText: "モバイル用ボトムタブバー設定"
-      },
-      objects: {
-        label: "オブジェクト権限",
-        helpText: "このアプリが公開するオブジェクト名"
-      },
-      apis: {
-        label: "API",
-        helpText: "API エンドポイント定義"
-      },
       defaultAgent: {
         label: "既定エージェント",
         helpText: "常駐アシスタントボタン用 AI エージェント"
@@ -1008,18 +989,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       requiredPermissions: {
         label: "必要な権限",
         helpText: "このアプリへのアクセスに必要な権限"
-      },
-      sharing: {
-        label: "共有",
-        helpText: "公開/内部/制限付きアクセス制御"
-      },
-      embed: {
-        label: "埋め込み",
-        helpText: "iFrame 埋め込み設定"
-      },
-      aria: {
-        label: "アクセシビリティ",
-        helpText: "アクセシビリティラベル"
       }
     }
   },

packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts

@@ -929,23 +929,23 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
     sections: {
       basics: {
         label: "基础信息",
-        description: "标识、版本与图标"
+        description: "应用标识与启用状态"
       },
       navigation: {
         label: "导航",
-        description: "菜单结构与首页"
+        description: "侧边栏菜单项与分区分组"
       },
       content: {
         label: "内容",
-        description: "对象、API 与默认智能体"
+        description: "环境助手绑定。对象与接口在 stack 上声明,不在 app 上"
       },
       branding: {
         label: "品牌",
         description: "主题色与 Logo"
       },
       access_and_sharing: {
         label: "访问与共享",
-        description: "权限、共享与嵌入"
+        description: "谁可以访问此应用。公开访问与嵌入按表单视图授予,不是应用级开关"
       }
     },
     fields: {
@@ -959,9 +959,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
       description: {
         label: "描述"
       },
-      version: {
-        label: "版本"
-      },
       icon: {
         label: "图标",
         helpText: "Lucide 图标名（如 users、briefcase）"
@@ -981,22 +978,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
         label: "区域",
         helpText: "将菜单项组织为可折叠分组"
       },
-      homePageId: {
-        label: "首页 ID",
-        helpText: "应用打开时跳转的页面"
-      },
-      mobileNavigation: {
-        label: "移动端导航",
-        helpText: "移动端底部 Tab 栏配置"
-      },
-      objects: {
-        label: "对象权限",
-        helpText: "此应用暴露的对象名"
-      },
-      apis: {
-        label: "API",
-        helpText: "API 端点定义"
-      },
       defaultAgent: {
         label: "默认智能体",
         helpText: "右下角浮动助手按钮调用的 AI 智能体"
@@ -1008,18 +989,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
       requiredPermissions: {
         label: "所需权限",
         helpText: "访问该应用需要的权限"
-      },
-      sharing: {
-        label: "共享",
-        helpText: "公开 / 内部 / 受限的访问控制"
-      },
-      embed: {
-        label: "嵌入",
-        helpText: "iFrame 嵌入配置"
-      },
-      aria: {
-        label: "无障碍",
-        helpText: "无障碍标签与角色"
       }
     }
   },