feat(approvals): retire process engine — approval is flow-node only (ADR-0019 P4/P5) (#1408)

* feat(approvals): remove process-driven engine; approval is flow-node only (ADR-0019 P4/P5)

Destructive removal of the standalone approval *process* engine. After ADR-0019
P1-P3 made approval work as a durable-pause flow node, this lands A4/A5: the
process model is gone and approval exists only as `type: 'approval'` on a Flow.

Removed:
- spec: ApprovalProcessSchema/Step/Action, approval.form.ts, `approvals` stack
  collection (metadata-collection, stack.zod, metadata-type-schemas,
  metadata-form-registry), process_hash pinning
- platform-objects: sys_approval_process object + nav + i18n; reframed
  sys_approval_request to node-era (process_name -> Source, no process_hash)
- plugin-approvals: action-executor.ts, process defineProcess/submit/recall,
  per-object process hooks -> single node-era global record-lock hook;
  decide() bridges decision -> engine resume; phase-b.test deleted,
  approval-service.test rewritten to drive the node
- rest: /approvals/processes + submit + recall routes (kept request reads +
  approve/reject decision routes wired to svc.decide)
- runtime: app-plugin process seeder
- cli/metadata: `approvals` stats + plural mapping

Migrated examples off `approvals:` to approval-node flows:
- app-crm: DiscountApprovalFlow
- app-showcase: BudgetApprovalFlow

connector_action is retained as a deliberate ADR-0018 open extension point.

Green: spec/platform-objects/plugin-approvals/runtime/rest/cli/metadata/
service-automation + app-crm/app-showcase.

* refactor(approvals): single decision path + give CRM example a mirror field

Self-review follow-ups on the P4/P5 removal:

- Drop decideApprovalNode (approval-node.ts) — it duplicated the resume
  orchestration now owned by the contract entrypoint ApprovalService.decide().
  Migrated approval-node.test.ts to drive decide() via attachAutomation, and
  removed the now-unused export. One decision/resume path, not two.
- Add a readonly approval_status select to crm_opportunity so the Discount
  Approval flow's approvalStatusField mirror has a real target (the mirror is
  try/caught, so before this it silently no-op'd in the example).

* test(objectql): migrate stale workflow fixture in metadata sweep to state-machine shape

The metadata-validation-sweep workflow fixture still used the legacy
workflow-rule shape (objectName/triggerType/criteria); `workflow` maps to
StateMachineSchema (id/initial/states) since the workflow→state-machine
migration, so the valid fixture failed validation. Updated it to a minimal
valid state machine. Pre-existing failure surfaced by Test Core; unrelated to
the approval node work but fixed here to keep CI green.

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>

Author: xuyushun441-sys

docs/adr/0019-approval-as-flow-node.md

@@ -1,6 +1,6 @@
 # ADR-0019: Collapse Approval into Flow — one engine, approval as a durable-pause node
 
-**Status**: Proposed (2026-05-31)
+**Status**: Accepted (2026-05-31) — fully implemented (A1–A5)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0018](./0018-unified-node-action-registry.md) (open action registry — approval becomes a consumer), [ADR-0009](./0009-execution-pinned-metadata.md) (execution pinning — reconcile to one mechanism), [ADR-0012](./0012-notification-platform.md) (outbox / `notify`), [ADR-0010](./0010-nl-to-flow-authoring.md) + [ADR-0011](./0011-actions-as-ai-tools.md) (AI authoring — the design center)
 **Revises**: ADR-0018's premise that Approval stays a separate paradigm with its own closed `ApprovalActionType` enum, and the "Workflow-Rule → Flow compiler" (M5) — both dropped here (greenfield, no legacy).
@@ -133,27 +133,33 @@ removal (A4/A5) can be reviewed and sequenced on its own once consumers move ove
    `approve` / `reject` edge. New correlation fields on `sys_approval_request`
    (`flow_run_id` / `flow_node_id` / `node_config_json`). The standalone process engine is left
    intact for the migration window.
-4. **A4 — delete parallel pieces.** ⏳ **Follow-up PR (destructive).** Remove
-   `action-executor.ts`, `ApprovalActionType`, `ApprovalProcessSchema` (top-level) +
-   `approval.form.ts`; route all actions through the ADR-0018 registry; retire `process_hash`
-   pinning in favor of Flow pinning. Gated on consumers (CRM examples, API routes, app seeders,
-   `metadata-type-schemas.ts` / `metadata-form-registry.ts`) migrating off the process model.
-5. **A5 — cleanup.** ⏳ **Follow-up PR.** Remove the `workflow_rule` paradigm remnants (the M5
-   compiler itself was already removed in #1398) and `connector_action` remnants in
-   `flow.zod.ts`; migrate `approval-service.test.ts` / `phase-b.test.ts` to drive the
-   Approval node.
-
-> **Landed in this PR:** A1–A3. The engine gained real durable suspend/resume (P1), spec gained
-> the Approval node contract (P2), and `plugin-approvals` gained the working node bridge (P3) —
-> all additive and green (spec 6605, service-automation 79, plugin-approvals 41). A4/A5 are the
-> destructive removal of the now-superseded standalone engine and are deliberately a separate PR.
+4. **A4 — delete parallel pieces.** ✅ **Done (this PR, destructive).** Removed
+   `action-executor.ts`, `ApprovalActionType`, `ApprovalProcessSchema` / `ApprovalStepSchema` /
+   `ApprovalActionSchema` (top-level) + `approval.form.ts`, the `sys_approval_process` object,
+   the `approvals` stack collection, the lifecycle auto-trigger, the REST `/approvals/processes`
+   + submit/recall routes, and the app-plugin process seeder; retired `process_hash` pinning in
+   favor of Flow pinning. All actions now route through the ADR-0018 registry. Consumers (CRM /
+   showcase examples, API routes, app seeders, `metadata-type-schemas.ts` /
+   `metadata-form-registry.ts`, CLI / metadata stats) migrated off the process model.
+5. **A5 — cleanup.** ✅ **Done (this PR).** The M5 compiler was already removed in #1398; the
+   `workflow_rule` paradigm remnants are gone with the process engine. `connector_action` is
+   **retained** — it is a deliberate open extension point on the ADR-0018 registry, not a process
+   remnant. `approval-service.test.ts` rewritten to drive the Approval node; `phase-b.test.ts`
+   deleted.
+
+> **Landed across two PRs:** A1–A3 (additive foundation) shipped first — the engine gained real
+> durable suspend/resume (P1), spec gained the Approval node contract (P2), and `plugin-approvals`
+> gained the working node bridge (P3). **This PR lands A4–A5**: the destructive removal of the
+> now-superseded standalone process engine. Approval exists *only* as a flow node. Green across
+> spec / platform-objects / plugin-approvals / runtime / rest / cli / metadata and both example apps.
 
 ## Migration map
 
 | Asset | Disposition |
 |:---|:---|
 | `plugin-approvals` execution loop + `action-executor.ts` | **Delete** (engine + actions now Flow's) |
-| `ApprovalActionType`, `connector_action` remnants, M5 compiler | **Delete** |
+| `ApprovalActionType`, M5 compiler (`workflow_rule`) | **Delete** |
+| `connector_action` | **Keep** — deliberate open extension point (ADR-0018), not a process remnant |
 | `ApprovalProcessSchema`, `approval.form.ts` (top-level authoring type) | **Deprecate / remove** — concepts → Approval node config + Flow graph |
 | `ApproverType`, `behavior`, `escalation`, `lockRecord`, `approvalStatusField` | **Re-home** → Approval node config schema |
 | Approver resolution (team/dept BFS/manager/role/queue) | **Keep** (move under node, ~verbatim) |

examples/app-crm/objectstack.config.ts

@@ -13,7 +13,6 @@ import * as emails from './src/emails/index.js';
 import { allHooks } from './src/hooks/index.js';
 import { allFlows } from './src/flows/index.js';
 import { HighValueDealWorkflow, StaleOpportunityWorkflow } from './src/workflows/index.js';
-import { DiscountApprovalProcess } from './src/approvals/index.js';
 import {
   SalesAssistantAgent,
   LookupContactTool,
@@ -105,7 +104,6 @@ export default defineStack({
   hooks: allHooks,
   flows: allFlows,
   workflows: [HighValueDealWorkflow, StaleOpportunityWorkflow],
-  approvals: [DiscountApprovalProcess],
   jobs: [LeadScoringJob, PipelineReportJob, RenewalSweepJob],
   emailTemplates: Object.values(emails),
 

examples/app-crm/src/approvals/discount-approval.approval.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Flow } from '@objectstack/spec/automation';
+
+/**
+ * Discount approval — ADR-0019 approval-as-flow-node.
+ *
+ * What used to be a standalone two-step approval *process* is now an ordinary
+ * autolaunched flow with two `approval` nodes. The flow suspends on each
+ * approval and resumes down the matching `approve` / `reject` edge:
+ *
+ *   start → manager_review ──approve──▶ finance_review ──approve──▶ end
+ *                          └─reject──▶ rejected                └─reject──▶ rejected
+ *
+ * Finance only signs off when the discount exceeds 30% — that gate is just a
+ * decision node on the approve edge out of the manager step.
+ */
+export const DiscountApprovalFlow: Flow = {
+  name: 'crm_discount_approval',
+  label: 'Opportunity Discount Approval',
+  description: 'Two-step approval for opportunities with significant discounts.',
+  type: 'autolaunched',
+
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Discount Above Threshold',
+      config: {
+        objectName: 'crm_opportunity',
+        triggerType: 'record-after-update',
+        condition: 'discount_percent > 20',
+      },
+    },
+    {
+      id: 'manager_review',
+      type: 'approval',
+      label: 'Manager Review',
+      config: {
+        approvers: [{ type: 'role', value: 'sales_manager' }],
+        behavior: 'first_response',
+        lockRecord: true,
+        approvalStatusField: 'approval_status',
+      },
+    },
+    {
+      id: 'needs_finance',
+      type: 'decision',
+      label: 'Discount Above 30%?',
+      config: { condition: 'discount_percent > 30' },
+    },
+    {
+      id: 'finance_review',
+      type: 'approval',
+      label: 'Finance Review',
+      config: {
+        approvers: [{ type: 'role', value: 'finance_approver' }],
+        behavior: 'unanimous',
+        lockRecord: true,
+        approvalStatusField: 'approval_status',
+      },
+    },
+    { id: 'approved', type: 'end', label: 'Approved' },
+    { id: 'rejected', type: 'end', label: 'Rejected' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'manager_review' },
+    { id: 'e2', source: 'manager_review', target: 'needs_finance', label: 'approve' },
+    { id: 'e3', source: 'manager_review', target: 'rejected', label: 'reject' },
+    { id: 'e4', source: 'needs_finance', target: 'finance_review', label: 'true' },
+    { id: 'e5', source: 'needs_finance', target: 'approved', label: 'false' },
+    { id: 'e6', source: 'finance_review', target: 'approved', label: 'approve' },
+    { id: 'e7', source: 'finance_review', target: 'rejected', label: 'reject' },
+  ],
+};

examples/app-crm/src/approvals/index.ts

@@ -4,7 +4,8 @@ import { OpportunityWonFlow } from './opportunity-won.flow.js';
 import { LeadQualificationFlow } from './lead-qualification.flow.js';
 import { RenewalReminderFlow } from './renewal-reminder.flow.js';
 import { ConvertLeadScreenFlow } from './convert-lead.flow.js';
+import { DiscountApprovalFlow } from './discount-approval.flow.js';
 
 export { ConvertLeadScreenFlow } from './convert-lead.flow.js';
 
-export const allFlows = [OpportunityWonFlow, LeadQualificationFlow, RenewalReminderFlow, ConvertLeadScreenFlow];
+export const allFlows = [OpportunityWonFlow, LeadQualificationFlow, RenewalReminderFlow, ConvertLeadScreenFlow, DiscountApprovalFlow];

examples/app-crm/src/flows/discount-approval.flow.ts

@@ -56,6 +56,19 @@ export const Opportunity = ObjectSchema.create({
       min: 0,
       max: 100,
     }),
+    // Mirror target for the Discount Approval flow's approval nodes
+    // (ADR-0019). The approval runtime writes the request status here; it is
+    // readonly to users so only the flow drives it.
+    approval_status: Field.select({
+      label: 'Approval Status',
+      readonly: true,
+      options: [
+        { label: 'Pending', value: 'pending', color: '#F59E0B' },
+        { label: 'Approved', value: 'approved', color: '#10B981' },
+        { label: 'Rejected', value: 'rejected', color: '#EF4444' },
+        { label: 'Recalled', value: 'recalled', color: '#94A3B8' },
+      ],
+    }),
     renewal_of: Field.lookup('crm_opportunity', {
       label: 'Renewal Of',
     }),

examples/app-crm/src/flows/index.ts

@@ -10,7 +10,6 @@ import { allReports } from './src/reports/index.js';
 import { allActions } from './src/actions/index.js';
 import { ComponentGalleryPage } from './src/pages/index.js';
 import { allFlows } from './src/flows/index.js';
-import { allApprovals } from './src/approvals/index.js';
 import { allWebhooks } from './src/webhooks/index.js';
 import { allJobs } from './src/jobs/index.js';
 import { allEmails } from './src/emails/index.js';
@@ -85,7 +84,6 @@ export default defineStack({
 
   // Logic
   flows: allFlows,
-  approvals: allApprovals,
   jobs: allJobs,
   emailTemplates: allEmails,
   webhooks: allWebhooks,

examples/app-crm/src/objects/opportunity.object.ts

@@ -67,7 +67,7 @@ export const COVERAGE = {
   },
   capabilityChains: {
     security: 'security/index.ts — roles + permission set (CRUD + FLS + RLS) + sharing + policy',
-    automation: 'flows/index.ts + approvals/index.ts + webhooks/index.ts + jobs/index.ts + emails/index.ts',
+    automation: 'flows/index.ts (incl. approval nodes) + webhooks/index.ts + jobs/index.ts + emails/index.ts',
     ai: 'agents/index.ts — agent + tool + skill',
   },
   i18nThemingPortals: {