fix(approvals): retire approval as a metadata type — flow-node only (ADR-0019) (#1410)

xuyushun441-sys · os-zhuang · web-flow · commit 25fedfdcb878 · 2026-05-31T19:56:39.000+08:00
ADR-0019 P4/P5 collapsed approval authoring into Flow (an Approval node,
`type: 'approval'`), but a few registrations of `approval` as a *standalone
metadata type* were left behind — contradicting metadata-type-schemas.ts,
which already dropped it. The result: Studio still rendered an "Approval
Processes" nav entry routing to a `metadata/approval` designer for a type
with no schema, and /meta/types still surfaced the type.

Remove the leftovers and their blast radius:
- Drop `approval` from the MetadataTypeSchema enum (spec + metadata-core mirror).
- Drop the `Approval Process` descriptor (and its `**/*.approval.ts` loader
  patterns) from DEFAULT_METADATA_TYPE_REGISTRY.
- Remove the hardcoded `nav_approvals` Studio nav item + its 4 hand-maintained
  locale labels.
- Strip the stale `approval` form block from the 4 *.metadata-forms.generated.ts.
- Update metadata-plugin.test.ts (drop `approval`; add a guard that it is now
  rejected as a metadata type).

Approval state (sys_approval_request / sys_approval_action, record lock, status
mirror) and the Approval *node* config (ApprovalNodeConfigSchema) are unchanged.

Verified: build clean (spec, metadata-core, platform-objects); 465 tests pass.

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
diff --git a/packages/metadata-core/src/types.ts b/packages/metadata-core/src/types.ts
@@ -29,7 +29,7 @@ export const MetadataTypeSchema = z.enum([
   'action',
   'flow',
   'workflow',
-  'approval',
+  // ADR-0019: `approval` is a flow node, not a metadata type.
   'job',
   'agent',
   'tool',
diff --git a/packages/platform-objects/src/apps/studio.app.ts b/packages/platform-objects/src/apps/studio.app.ts
@@ -215,14 +215,8 @@ export const STUDIO_APP: App = {
           params: { type: 'workflow', package: '{active_package}' },
           icon: 'zap',
         },
-        {
-          id: 'nav_approvals',
-          type: 'component',
-          label: 'Approval Processes',
-          componentRef: 'metadata:resource',
-          params: { type: 'approval', package: '{active_package}' },
-          icon: 'check-circle',
-        },
+        // ADR-0019: no standalone "Approval Processes" nav — approvals are
+        // authored as Approval nodes inside a Flow (see nav_flows above).
       ],
     },
     {
diff --git a/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts
@@ -788,65 +788,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       }
     }
   },
-  approval: {
-    label: "Approval Process",
-    sections: {
-      basics: {
-        label: "Basics",
-        description: "Approval process identity and the object it gates."
-      },
-      entry_rules: {
-        label: "Entry rules",
-        description: "Who can submit, and what happens to the record while pending."
-      },
-      steps: {
-        label: "Steps",
-        description: "Ordered approval chain — each step picks the approver and decides routing."
-      },
-      escalation_and_outcomes: {
-        label: "Escalation & outcomes",
-        description: "SLA, escalation, and post-decision actions."
-      }
-    },
-    fields: {
-      name: {
-        helpText: "Unique identifier (snake_case)"
-      },
-      label: {
-        helpText: "Display name (e.g., \"Contract Approval\")"
-      },
-      object: {
-        helpText: "Which object needs approval"
-      },
-      active: {
-        helpText: "Enable/disable this approval process"
-      },
-      description: {
-        helpText: "What gets approved and why"
-      },
-      entryCriteria: {
-        helpText: "CEL expression: users can submit only when this is true"
-      },
-      lockRecord: {
-        helpText: "Lock record from editing while approval is pending"
-      },
-      approvalStatusField: {
-        helpText: "Field name to mirror approval status (e.g., \"approval_status\")"
-      },
-      steps: {
-        helpText: "Approval steps in order — each step defines who approves and what happens"
-      },
-      escalation: {
-        helpText: "Auto-escalate or auto-approve after timeout"
-      },
-      onFinalApprove: {
-        helpText: "Actions when all steps approved (e.g., update status)"
-      },
-      onFinalReject: {
-        helpText: "Actions when rejected (e.g., notify submitter)"
-      }
-    }
-  },
   job: {
     label: "Background Job"
   },
diff --git a/packages/platform-objects/src/apps/translations/en.ts b/packages/platform-objects/src/apps/translations/en.ts
@@ -123,7 +123,6 @@ export const en: TranslationData = {
         group_automation: { label: 'Automation' },
         nav_flows: { label: 'Flows' },
         nav_workflows: { label: 'Workflow Rules' },
-        nav_approvals: { label: 'Approval Processes' },
         group_ai: { label: 'AI' },
         nav_agents: { label: 'Agents' },
         nav_tools: { label: 'Tools' },
diff --git a/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts
@@ -788,65 +788,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       }
     }
   },
-  approval: {
-    label: "Proceso de aprobación",
-    sections: {
-      basics: {
-        label: "Aspectos básicos",
-        description: "Identidad del proceso de aprobación y el objeto que controla."
-      },
-      entry_rules: {
-        label: "Reglas de entrada",
-        description: "Quién puede enviar y qué ocurre con el registro mientras está pendiente."
-      },
-      steps: {
-        label: "Pasos",
-        description: "Cadena de aprobación ordenada — cada paso elige aprobador y decide el enrutado."
-      },
-      escalation_and_outcomes: {
-        label: "Escalado y resultados",
-        description: "SLA, escalado y acciones posteriores a la decisión."
-      }
-    },
-    fields: {
-      name: {
-        helpText: "Identificador único (snake_case)"
-      },
-      label: {
-        helpText: "Nombre mostrado (p. ej., \"Contract Approval\")"
-      },
-      object: {
-        helpText: "Qué objeto necesita aprobación"
-      },
-      active: {
-        helpText: "Activa/desactiva este proceso de aprobación"
-      },
-      description: {
-        helpText: "Qué se aprueba y por qué"
-      },
-      entryCriteria: {
-        helpText: "Expresión CEL: los usuarios solo pueden enviar cuando esto sea true"
-      },
-      lockRecord: {
-        helpText: "Bloquea la edición del registro mientras la aprobación está pendiente"
-      },
-      approvalStatusField: {
-        helpText: "Nombre de campo para reflejar el estado de aprobación (p. ej., \"approval_status\")"
-      },
-      steps: {
-        helpText: "Pasos de aprobación en orden — cada paso define quién aprueba y qué ocurre"
-      },
-      escalation: {
-        helpText: "Escala o aprueba automáticamente tras el tiempo de espera"
-      },
-      onFinalApprove: {
-        helpText: "Acciones cuando todos los pasos se aprueban (p. ej., actualizar estado)"
-      },
-      onFinalReject: {
-        helpText: "Acciones al rechazar (p. ej., notificar al remitente)"
-      }
-    }
-  },
   job: {
     label: "Trabajo en segundo plano"
   },
diff --git a/packages/platform-objects/src/apps/translations/es-ES.ts b/packages/platform-objects/src/apps/translations/es-ES.ts
@@ -100,7 +100,6 @@ export const esES: TranslationData = {
         group_automation: { label: 'Automatización' },
         nav_flows: { label: 'Flujos' },
         nav_workflows: { label: 'Reglas de flujo de trabajo' },
-        nav_approvals: { label: 'Procesos de aprobación' },
         group_ai: { label: 'IA' },
         nav_agents: { label: 'Agentes' },
         nav_tools: { label: 'Herramientas' },
diff --git a/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts
@@ -788,65 +788,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       }
     }
   },
-  approval: {
-    label: "承認プロセス",
-    sections: {
-      basics: {
-        label: "基本",
-        description: "承認プロセス ID と対象オブジェクト。"
-      },
-      entry_rules: {
-        label: "エントリールール",
-        description: "送信可能者と保留中レコードの動作。"
-      },
-      steps: {
-        label: "ステップ",
-        description: "順序付き承認チェーン — 各ステップで承認者とルーティングを決定。"
-      },
-      escalation_and_outcomes: {
-        label: "エスカレーションと結果",
-        description: "SLA、エスカレーション、決定後アクション。"
-      }
-    },
-    fields: {
-      name: {
-        helpText: "一意識別子（snake_case）"
-      },
-      label: {
-        helpText: "表示名（例: \"Contract Approval\"）"
-      },
-      object: {
-        helpText: "承認が必要なオブジェクト"
-      },
-      active: {
-        helpText: "この承認プロセスの有効/無効"
-      },
-      description: {
-        helpText: "承認対象と理由"
-      },
-      entryCriteria: {
-        helpText: "CEL 式: これが true の場合のみユーザーが送信可能"
-      },
-      lockRecord: {
-        helpText: "承認保留中はレコード編集をロック"
-      },
-      approvalStatusField: {
-        helpText: "承認状態を反映するフィールド名（例: \"approval_status\"）"
-      },
-      steps: {
-        helpText: "順序付き承認ステップ — 各ステップで承認者と処理を定義"
-      },
-      escalation: {
-        helpText: "タイムアウト後に自動エスカレーションまたは自動承認"
-      },
-      onFinalApprove: {
-        helpText: "全ステップ承認時のアクション（例: ステータス更新）"
-      },
-      onFinalReject: {
-        helpText: "却下時のアクション（例: 申請者へ通知）"
-      }
-    }
-  },
   job: {
     label: "バックグラウンドジョブ"
   },
diff --git a/packages/platform-objects/src/apps/translations/ja-JP.ts b/packages/platform-objects/src/apps/translations/ja-JP.ts
@@ -100,7 +100,6 @@ export const jaJP: TranslationData = {
         group_automation: { label: '自動化' },
         nav_flows: { label: 'フロー' },
         nav_workflows: { label: 'ワークフロールール' },
-        nav_approvals: { label: '承認プロセス' },
         group_ai: { label: 'AI' },
         nav_agents: { label: 'エージェント' },
         nav_tools: { label: 'ツール' },
diff --git a/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts b/packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts
@@ -788,65 +788,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
       }
     }
   },
-  approval: {
-    label: "审批流",
-    sections: {
-      basics: {
-        label: "基础信息",
-        description: "名称与目标对象"
-      },
-      entry_rules: {
-        label: "进入规则",
-        description: "何时进入审批"
-      },
-      steps: {
-        label: "审批步骤",
-        description: "逐级审批配置"
-      },
-      escalation_and_outcomes: {
-        label: "升级与结果",
-        description: "超时升级与最终处理"
-      }
-    },
-    fields: {
-      name: {
-        helpText: "唯一标识符（snake_case）"
-      },
-      label: {
-        helpText: "显示名（如：\"合同审批\"）"
-      },
-      object: {
-        helpText: "需要审批的对象"
-      },
-      active: {
-        helpText: "启用或禁用此审批流"
-      },
-      description: {
-        helpText: "审批的对象与原因"
-      },
-      entryCriteria: {
-        helpText: "CEL 表达式：满足时用户可提交"
-      },
-      lockRecord: {
-        helpText: "审批待处理期间锁定记录，禁止编辑"
-      },
-      approvalStatusField: {
-        helpText: "用于镜像审批状态的字段名（如 \"approval_status\"）"
-      },
-      steps: {
-        helpText: "按顺序排列的审批步骤——每一步定义由谁审批以及结果"
-      },
-      escalation: {
-        helpText: "超时后自动升级或自动通过"
-      },
-      onFinalApprove: {
-        helpText: "所有步骤通过后的动作（如更新状态）"
-      },
-      onFinalReject: {
-        helpText: "被拒绝后的动作（如通知提交人）"
-      }
-    }
-  },
   job: {
     label: "后台作业"
   },
diff --git a/packages/platform-objects/src/apps/translations/zh-CN.ts b/packages/platform-objects/src/apps/translations/zh-CN.ts
@@ -100,7 +100,6 @@ export const zhCN: TranslationData = {
         group_automation: { label: '自动化' },
         nav_flows: { label: '流程' },
         nav_workflows: { label: '工作流规则' },
-        nav_approvals: { label: '审批流程' },
         group_ai: { label: 'AI' },
         nav_agents: { label: '智能体' },
         nav_tools: { label: '工具' },
diff --git a/packages/spec/src/kernel/metadata-plugin.test.ts b/packages/spec/src/kernel/metadata-plugin.test.ts
@@ -20,7 +20,7 @@ describe('MetadataPluginProtocol', () => {
       const types = [
         'object', 'field', 'trigger', 'validation', 'hook',
         'view', 'page', 'dashboard', 'app', 'action', 'report',
-        'flow', 'workflow', 'approval',
+        'flow', 'workflow',
         'datasource', 'translation', 'router', 'function', 'service',
         'permission', 'profile', 'role',
         'agent', 'tool', 'skill',
@@ -36,6 +36,10 @@ describe('MetadataPluginProtocol', () => {
       expect(() => MetadataTypeSchema.parse('widget')).toThrow();
       expect(() => MetadataTypeSchema.parse('')).toThrow();
     });
+
+    it('should reject `approval` as a metadata type (ADR-0019: approval is a flow node)', () => {
+      expect(() => MetadataTypeSchema.parse('approval')).toThrow();
+    });
   });
 
   describe('MetadataTypeRegistryEntrySchema', () => {
diff --git a/packages/spec/src/kernel/metadata-plugin.zod.ts b/packages/spec/src/kernel/metadata-plugin.zod.ts
@@ -88,7 +88,8 @@ export const MetadataTypeSchema = lazySchema(() => z.enum([
   // Automation Protocol
   'flow',        // Visual logic flows (FlowSchema)
   'workflow',    // State machines (StateMachineSchema)
-  'approval',    // Approval processes (ApprovalSchema)
+  // ADR-0019: `approval` is no longer a metadata type — approvals are authored
+  // as Approval nodes inside a `flow`.
   'job',         // Background / scheduled jobs (JobSchema)
 
   // System Protocol
@@ -604,10 +605,11 @@ export const DEFAULT_METADATA_TYPE_REGISTRY: MetadataTypeRegistryEntry[] = [
   { type: 'action', label: 'Action', filePatterns: ['**/*.action.ts', '**/*.action.yml'], supportsOverlay: false, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: false, loadOrder: 50, domain: 'ui' },
   { type: 'report', label: 'Report', filePatterns: ['**/*.report.ts', '**/*.report.yml'], supportsOverlay: true, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: false, loadOrder: 60, domain: 'ui' },
 
-  // Automation Protocol — flow/workflow/approval are executionPinned (ADR-0009)
+  // Automation Protocol — flow/workflow are executionPinned (ADR-0009).
+  // ADR-0019: there is no `approval` metadata type — approvals are Approval
+  // nodes inside a `flow`, so they load and version with their enclosing flow.
   { type: 'flow', label: 'Flow', filePatterns: ['**/*.flow.ts', '**/*.flow.yml', '**/*.flow.json'], supportsOverlay: false, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: 'automation' },
   { type: 'workflow', label: 'Workflow', filePatterns: ['**/*.workflow.ts', '**/*.workflow.yml'], supportsOverlay: false, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: 'automation' },
-  { type: 'approval', label: 'Approval Process', filePatterns: ['**/*.approval.ts', '**/*.approval.yml'], supportsOverlay: false, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: true, executionPinned: true, loadOrder: 80, domain: 'automation' },
   { type: 'job', label: 'Background Job', filePatterns: ['**/*.job.ts', '**/*.job.yml', '**/*.job.json'], supportsOverlay: false, allowOrgOverride: true, allowRuntimeCreate: true, supportsVersioning: false, executionPinned: false, loadOrder: 80, domain: 'automation' },
 
   // System Protocol
