feat(approvals): publish approval node config schema + xRef reference hints (ADR-0018/0019) (#1412)

Make the engine the single source of truth for the Approval node's property
form so the Studio flow designer renders from the backend rather than a
hardcoded client form.

- plugin-approvals: publish `configSchema` (getApprovalNodeConfigJsonSchema())
  on the approval ActionDescriptor (ADR-0018 §configSchema).
- spec: annotate `approvalStatusField` with `.meta({ xRef: { kind:
  'object-field', objectSource: '$trigger' } })` so the designer renders an
  object-field picker (scoped to the flow's trigger object) instead of free
  text. Single `.meta()` carries both description and annotation so neither is
  dropped through z.toJSONSchema.
- examples (app-crm, app-showcase): require the `approvals` capability so the
  `approval` flow node is contributed to the engine and surfaces in the palette.

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

Author: xuyushun441-sys

examples/app-crm/objectstack.config.ts

@@ -65,8 +65,11 @@ export default defineStack({
   },
 
   // Auto-resolved by the CLI; `ui` enables the Studio shell, `automation` loads
-  // AutomationServicePlugin + node packs so screen flows can execute.
-  requires: ['ui', 'automation'],
+  // AutomationServicePlugin + node packs so screen flows can execute, and
+  // `approvals` loads ApprovalsServicePlugin so the `approval` flow node is
+  // contributed to the engine (ADR-0019) — required for the discount-approval
+  // flow to compile/register and to surface the node in the designer palette.
+  requires: ['ui', 'automation', 'approvals'],
 
   // Infrastructure
   datasources: [CrmDatasource, CrmAnalyticsDatasource],

examples/app-showcase/objectstack.config.ts

@@ -49,7 +49,9 @@ export default defineStack({
     description: 'Kitchen-sink workspace covering all metadata types, all view types, and the major capability chains.',
   },
 
-  requires: ['ui', 'automation'],
+  // `approvals` loads ApprovalsServicePlugin so the `approval` flow node
+  // (ADR-0019) is contributed to the engine — the showcase flows use it.
+  requires: ['ui', 'automation', 'approvals'],
 
   // Infrastructure
   datasources: allDatasources,

packages/plugins/plugin-approvals/src/approval-node.ts

@@ -20,6 +20,7 @@
 import {
   defineActionDescriptor,
   ApprovalNodeConfigSchema,
+  getApprovalNodeConfigJsonSchema,
   APPROVAL_NODE_TYPE,
   type ApprovalNodeConfig,
 } from '@objectstack/spec/automation';
@@ -74,6 +75,10 @@ export function registerApprovalNode(
       // Human decision: the run suspends here awaiting an external reply.
       supportsPause: true,
       isAsync: true,
+      // Publish the node's config contract (ADR-0018 §configSchema) so the
+      // Studio flow designer renders the Approval property form from the engine
+      // rather than a hardcoded client form — the engine owns the shape.
+      configSchema: getApprovalNodeConfigJsonSchema(),
     }),
     async execute(node, variables, context) {
       const parsed = ApprovalNodeConfigSchema.safeParse(node.config ?? {});

packages/spec/src/automation/approval.zod.ts

@@ -118,9 +118,43 @@ export const ApprovalNodeConfigSchema = lazySchema(() => z.object({
    * object. Omitted ⇒ status is exposed only via `sys_approval_request`.
    */
   approvalStatusField: z.string().optional()
-    .describe('Business-object field to mirror request status onto'),
+    // `xRef` marks this string as a typed reference (ADR-0018 §configSchema):
+    // the Studio designer renders an object-field picker instead of free text.
+    // `objectSource: '$trigger'` resolves the field catalog from the flow's
+    // trigger object (the record this approval acts on). A single `.meta()`
+    // carries both description and the annotation so neither is dropped.
+    .meta({
+      description: 'Business-object field to mirror request status onto',
+      xRef: { kind: 'object-field', objectSource: '$trigger' },
+    }),
 
   /** Optional per-node SLA escalation. */
   escalation: ApprovalEscalationSchema.optional().describe('Per-node SLA escalation'),
 }));
 export type ApprovalNodeConfig = z.infer<typeof ApprovalNodeConfigSchema>;
+
+/**
+ * JSON Schema for {@link ApprovalNodeConfigSchema}, memoized.
+ *
+ * Published on the Approval action descriptor's `configSchema`
+ * (ADR-0018/0019) so the **engine** is the single source of truth for the
+ * node's config contract: the Studio flow designer renders the Approval node's
+ * property form from this schema (rather than a hardcoded client form), and the
+ * same schema backs `registerFlow()` config validation. Derived with Zod v4's
+ * `z.toJSONSchema` in `input` mode (the author-facing shape — default-bearing
+ * fields are optional). Lazily computed so the wrapped schema is only resolved
+ * when a descriptor is actually built.
+ */
+let cachedApprovalNodeConfigJsonSchema: unknown;
+export function getApprovalNodeConfigJsonSchema(): unknown {
+  if (cachedApprovalNodeConfigJsonSchema === undefined) {
+    cachedApprovalNodeConfigJsonSchema = z.toJSONSchema(ApprovalNodeConfigSchema, {
+      target: 'draft-2020-12',
+      io: 'input',
+      // Approval config has no unrepresentable constructs today; keep the
+      // designer resilient if one is ever added rather than throwing at boot.
+      unrepresentable: 'any',
+    });
+  }
+  return cachedApprovalNodeConfigJsonSchema;
+}