fix(studio): flow wait-node inspector tolerates the loose config shape (#1974)

The wait inspector read only `waitEventConfig.{eventType,signalName,…}`, but the
engine also accepts the looser `config.{eventType,…}` shape that the canonical
showcase_budget_approval (and AI-authored flows) use — so a showcase-shaped wait
node showed blank fields in the designer.

Flow config fields gain `fallbackPath`: tolerant read (loose shape displays +
dependent fields reveal), canonical write that prunes the fallback
(migrate-on-edit), and the fallback config key suppressed from Advanced. The
`wait` fields fall back to `config.*`. Designer now matches engine tolerance.

Refs #1954 (ADR-0044).

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

Author: os-zhuang

.changeset/flow-wait-loose-config-fallback.md

@@ -0,0 +1,18 @@
+---
+"@object-ui/app-shell": patch
+---
+
+fix(studio): flow wait-node inspector tolerates the loose `config` shape
+
+The wait-node property form read only the spec-canonical
+`waitEventConfig.{eventType,signalName,…}`, but the engine also accepts a looser
+`config.{eventType,…}` shape — which the canonical `showcase_budget_approval`
+(and AI-authored flows) use. So a showcase-shaped wait node opened in the
+designer showed blank "Wait for" / "Signal name" fields.
+
+Flow config fields gain an optional `fallbackPath`: reads fall back to it (so
+loose-shape wait nodes display, and dependent fields reveal), writes target the
+canonical path and prune the fallback (migrate-on-edit), and the fallback's
+config key is suppressed from the Advanced block. The `wait` fields now fall
+back to `config.*`, so the designer matches the engine's tolerance. Pairs with
+the ADR-0044 revise-loop authoring (#1954).

packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.tsx

@@ -30,6 +30,7 @@ import {
   getFieldValue,
   configKeyOf,
   FLOW_NODE_TYPE_OPTIONS,
+  type FlowConfigField,
 } from './flow-node-config';
 import { jsonSchemaToFlowFields } from './json-schema-to-fields';
 import { useActionConfigSchemas } from '../previews/useFlowNodePalette';
@@ -157,6 +158,9 @@ export function FlowNodeInspector({ selection, draft, onPatch, onClearSelection,
     for (const f of fields) {
       const k = configKeyOf(f);
       if (k) s.add(k);
+      // A loose-shape fallback rooted at `config` is claimed too, so a tolerated
+      // legacy key (e.g. a wait node's `config.eventType`) never leaks to Advanced.
+      if (f.fallbackPath && f.fallbackPath.length >= 2 && f.fallbackPath[0] === 'config') s.add(f.fallbackPath[1]);
     }
     return s;
   }, [fields]);
@@ -196,8 +200,12 @@ export function FlowNodeInspector({ selection, draft, onPatch, onClearSelection,
   // Screen nodes (and the `user_task` alias) get a live end-user preview.
   const isScreen = node.type === 'screen' || node.type === 'user_task';
 
-  const setField = (path: string[], value: unknown) => {
-    const nextNode = setAtPath(node, path, value);
+  const setField = (field: FlowConfigField, value: unknown) => {
+    const path = field.path;
+    let nextNode = setAtPath(node, path, value);
+    // Migrate-on-edit: writing the canonical path drops any looser fallback
+    // location, so the node never carries a stale duplicate (engine + designer agree).
+    if (field.fallbackPath) nextNode = setAtPath(nextNode, field.fallbackPath, undefined);
     const patch: Record<string, unknown> = { nodes: spliceArray(nodes, index, nextNode) };
     // Decision branches drive routing — mirror them onto the node's outgoing
     // edges so the engine/simulator can actually branch (they read
@@ -285,7 +293,7 @@ export function FlowNodeInspector({ selection, draft, onPatch, onClearSelection,
           key={field.id}
           field={field}
           value={getFieldValue(node, field)}
-          onCommit={(v) => setField(field.path, v)}
+          onCommit={(v) => setField(field, v)}
           disabled={readOnly}
           locale={locale}
           context={{ draft, node }}

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { fieldsForNodeType, isFieldVisible } from './flow-node-config';
+import { fieldsForNodeType, isFieldVisible, getFieldValue } from './flow-node-config';
 
 describe('start node trigger-field gating (#5)', () => {
   const fields = fieldsForNodeType('start');
@@ -49,3 +49,30 @@ describe('approval node config (ADR-0044)', () => {
     expect(isFieldVisible(maxRevisions!, { id: 'a', type: 'approval' }, fields)).toBe(true);
   });
 });
+
+
+describe('wait node loose-config fallback (ADR-0044 showcase parity)', () => {
+  const fields = fieldsForNodeType('wait');
+  const eventType = fields.find((f) => f.id === 'waitEventConfig.eventType')!;
+  const signalName = fields.find((f) => f.id === 'waitEventConfig.signalName')!;
+
+  it('reads the canonical waitEventConfig shape', () => {
+    const node = { id: 'w', type: 'wait', waitEventConfig: { eventType: 'signal', signalName: 'x' } };
+    expect(getFieldValue(node, eventType)).toBe('signal');
+    expect(getFieldValue(node, signalName)).toBe('x');
+  });
+
+  it('falls back to a loose config shape the engine also accepts', () => {
+    // showcase_budget_approval authors the wait node as `config: { eventType, signalName }`.
+    const node = { id: 'w', type: 'wait', config: { eventType: 'signal', signalName: 'budget_revision' } };
+    expect(getFieldValue(node, eventType)).toBe('signal');
+    expect(getFieldValue(node, signalName)).toBe('budget_revision');
+    // The dependent field reveals because its controller resolves via the fallback.
+    expect(isFieldVisible(signalName, node, fields)).toBe(true);
+  });
+
+  it('prefers the canonical path when both shapes are present', () => {
+    const node = { id: 'w', type: 'wait', waitEventConfig: { eventType: 'timer' }, config: { eventType: 'signal' } };
+    expect(getFieldValue(node, eventType)).toBe('timer');
+  });
+});

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.ts

@@ -118,6 +118,14 @@ export interface FlowConfigField {
    * the spec's top-level `node.waitEventConfig.eventType`.
    */
   path: string[];
+  /**
+   * Optional secondary read location used when `path` holds no value — lets the
+   * inspector tolerate a looser on-disk shape the engine also accepts (e.g. a
+   * `wait` node authored with `config.eventType` instead of the spec-canonical
+   * `waitEventConfig.eventType`). Reads fall back to it; the inspector writes the
+   * canonical `path` and prunes the fallback (migrate-on-edit).
+   */
+  fallbackPath?: string[];
   /** Human-readable field label (English — repo is English-only). */
   label: string;
   kind: FlowConfigFieldKind;
@@ -471,23 +479,27 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
         { value: 'condition', label: 'Condition' },
       ],
       defaultValue: 'timer',
+      fallbackPath: ['config', 'eventType'],
     }),
     at('waitEventConfig', 'timerDuration', 'Duration', 'text', {
       placeholder: 'PT1H · P3D',
       help: 'ISO 8601 duration (e.g. PT1H, P3D).',
       showWhen: { field: 'waitEventConfig.eventType', equals: ['timer'] },
+      fallbackPath: ['config', 'timerDuration'],
     }),
     at('waitEventConfig', 'signalName', 'Signal name', 'text', {
       placeholder: 'contract.renewed',
       showWhen: { field: 'waitEventConfig.eventType', equals: ['signal', 'webhook'] },
+      fallbackPath: ['config', 'signalName'],
     }),
-    at('waitEventConfig', 'timeoutMs', 'Timeout (ms)', 'number', { placeholder: '3600000' }),
+    at('waitEventConfig', 'timeoutMs', 'Timeout (ms)', 'number', { placeholder: '3600000', fallbackPath: ['config', 'timeoutMs'] }),
     at('waitEventConfig', 'onTimeout', 'On timeout', 'select', {
       options: [
         { value: 'fail', label: 'Fail' },
         { value: 'continue', label: 'Continue' },
       ],
       defaultValue: 'fail',
+      fallbackPath: ['config', 'onTimeout'],
     }),
   ],
   subflow: [
@@ -595,14 +607,19 @@ export function fieldsForNodeType(type?: string): FlowConfigField[] {
   return FLOW_NODE_CONFIG[canonical] ?? [];
 }
 
-/** Read the current value at a field's node path. */
+/** Read the current value at a field's node path, falling back to `fallbackPath`. */
 export function getFieldValue(node: Record<string, unknown> | null | undefined, field: FlowConfigField): unknown {
-  let cur: unknown = node;
-  for (const seg of field.path) {
-    if (cur && typeof cur === 'object' && !Array.isArray(cur)) cur = (cur as Record<string, unknown>)[seg];
-    else return undefined;
-  }
-  return cur;
+  const read = (path: string[]): unknown => {
+    let cur: unknown = node;
+    for (const seg of path) {
+      if (cur && typeof cur === 'object' && !Array.isArray(cur)) cur = (cur as Record<string, unknown>)[seg];
+      else return undefined;
+    }
+    return cur;
+  };
+  const primary = read(field.path);
+  if (primary !== undefined) return primary;
+  return field.fallbackPath ? read(field.fallbackPath) : undefined;
 }
 
 /**