fix(metadata-admin): flow data-picker — scope-aware ref validation + array assignments + script bare mode (#1934) (#1975)

Follow-ups to the variable data-picker (#1973):

- Scope-aware "unknown reference" warning — pairs the picker with the inline
  validation the issue asked for: flags a typed reference whose ROOT isn't in
  scope at the node, with a nearest-match "did you mean?" hint. Deliberately
  conservative to avoid false positives (root-only so `record.<anything>` is
  fine when `record` is in scope; skips function/macro calls, string literals,
  CEL keywords and runtime globals like `env` / `$error`; typo hint only within
  edit distance 2). Non-blocking amber; the ADR-0032 brace error still wins.
  CEL for expression fields, `{…}` holes for templates. New pure `flow-ref-check`
  module with unit tests.
- Assignment values authored in the array form `[{ variable, value }]` now
  render in the key/value editor (and so get the picker) instead of falling back
  to the Advanced JSON block. The editor reads BOTH the object-map and array
  shapes and preserves whichever was authored. Round-trip unit tests.
- A script `code` body (JS/TS, not a `{var}` template) now inserts BARE
  references via a new `refMode` field-schema override — `{x}` is a syntax error
  in a script. Fixes a brace-mode regression from #1973 where every textarea was
  treated as a template.

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

Author: os-zhuang

.changeset/flow-ref-validation.md

@@ -0,0 +1,5 @@
+---
+'@object-ui/app-shell': patch
+---
+
+Flow builder data-picker follow-ups (#1934): (1) a scope-aware "unknown reference" warning pairs the picker with inline validation — a typed reference whose root isn't in scope at the node is flagged with a nearest-match "did you mean?" hint (conservative: root-only, skips function calls / string literals / runtime globals; non-blocking amber). (2) Assignment values authored in the array form `[{ variable, value }]` now render in the key/value editor (and get the picker) instead of falling back to Advanced JSON; the editor reads both the object-map and array shapes and preserves whichever was authored. (3) A script `code` body (JS/TS, not a `{var}` template) now inserts bare references via a `refMode` field override — `{x}` is a syntax error in a script.

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

@@ -31,6 +31,7 @@ import { edgeKey, conditionText } from '../previews/flow-canvas-layout';
 import { validateExpressionClient } from './expression-validate';
 import { useFlowScope } from './useFlowScope';
 import { VariableTextInput } from './VariableTextInput';
+import { findUnknownRefs, scopeRoots, describeUnknownRefs } from './flow-ref-check';
 
 interface FlowEdge {
   id?: string;
@@ -233,9 +234,21 @@ export function FlowEdgeInspector({ selection, draft, onPatch, onClearSelection,
         // ADR-0032 — flag a malformed edge guard (e.g. `{record.x}` brace-in-CEL)
         // inline, with the same corrective message as build/agent validation.
         const issue = isDefault ? null : validateExpressionClient('predicate', edge.condition);
-        return issue ? (
-          <p className="text-[11px] leading-snug text-destructive" role="alert">
-            {issue.message}
+        if (issue) {
+          return (
+            <p className="text-[11px] leading-snug text-destructive" role="alert">
+              {issue.message}
+            </p>
+          );
+        }
+        // #1934 — gentle scope-aware "unknown reference" warning (refs in scope
+        // at the edge's SOURCE node), once the guard is structurally valid.
+        const unknown = isDefault
+          ? []
+          : findUnknownRefs(conditionText(edge.condition), 'predicate', scopeRoots(scopeGroups.flatMap((g) => g.refs)));
+        return unknown.length > 0 ? (
+          <p className="text-[11px] leading-snug text-amber-600 dark:text-amber-400" role="note">
+            {describeUnknownRefs(unknown)}
           </p>
         ) : null;
       })()}

packages/app-shell/src/views/metadata-admin/inspectors/FlowKeyValueField.shape.test.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { toEntries, rowsToValue, type Row } from './FlowKeyValueField';
+
+const row = (key: string, raw: string): Row => ({ id: key, key, raw });
+
+describe('FlowKeyValueField shape handling (#1934 — assignment array form)', () => {
+  it('reads the object-map shape into entries', () => {
+    expect(toEntries({ a: 1, b: 'x' })).toEqual([
+      ['a', 1],
+      ['b', 'x'],
+    ]);
+  });
+
+  it('reads the assignment ARRAY shape ({variable|name|key, value}) into entries', () => {
+    expect(toEntries([{ variable: 'lead_score', value: 0 }, { variable: 'qualified', value: false }])).toEqual([
+      ['lead_score', 0],
+      ['qualified', false],
+    ]);
+    expect(toEntries([{ name: 'a', value: 1 }, { key: 'b', value: 2 }])).toEqual([
+      ['a', 1],
+      ['b', 2],
+    ]);
+  });
+
+  it('ignores a non-object / non-array value', () => {
+    expect(toEntries('nope')).toEqual([]);
+    expect(toEntries(null)).toEqual([]);
+  });
+
+  it('writes back the OBJECT shape, smart-parsing + de-duping', () => {
+    const out = rowsToValue([row('amount', '30'), row('flag', 'true'), row('', 'skip'), row('amount', 'dupe')], false);
+    expect(out).toEqual({ amount: 30, flag: true });
+  });
+
+  it('writes back the ARRAY shape, preserving [{variable, value}]', () => {
+    const out = rowsToValue([row('lead_score', '0'), row('qualified', 'false'), row('ref', '{record.id}')], true);
+    expect(out).toEqual([
+      { variable: 'lead_score', value: 0 },
+      { variable: 'qualified', value: false },
+      { variable: 'ref', value: '{record.id}' },
+    ]);
+  });
+
+  it('round-trips an array-shape assignment without changing its shape', () => {
+    const stored = [{ variable: 'lead_score', value: 0 }, { variable: 'enrichment_data', value: null }];
+    const rows = toEntries(stored).map(([k, v]) => row(k, v == null ? '' : String(v)));
+    const out = rowsToValue(rows, /* arrayShape */ true);
+    expect(Array.isArray(out)).toBe(true);
+    expect((out as Array<Record<string, unknown>>).map((e) => e.variable)).toEqual(['lead_score', 'enrichment_data']);
+  });
+});

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

@@ -24,7 +24,7 @@ import { uniqueId } from './_shared';
 import { VariableTextInput } from './VariableTextInput';
 import type { ScopeGroup } from './useFlowScope';
 
-interface Row {
+export interface Row {
   id: string;
   key: string;
   /** Display string for the value cell. */
@@ -64,27 +64,64 @@ function parseValue(raw: string): unknown {
   return raw;
 }
 
-function toRows(obj: Record<string, unknown>, existingIds: string[]): Row[] {
+/**
+ * Read the stored value as `[key, value]` entries, accepting BOTH shapes a
+ * key/value config field can hold: the common object map (`{ var: value }`) and
+ * the assignment-node ARRAY form (`[{ variable|name|key, value }]`). The shape
+ * is preserved on write (see {@link rowsToValue}).
+ */
+export function toEntries(value: unknown): Array<[string, unknown]> {
+  if (Array.isArray(value)) {
+    return value
+      .filter((it): it is Record<string, unknown> => isPlainObject(it))
+      .map((it) => {
+        const k = it.variable ?? it.name ?? it.key;
+        return [typeof k === 'string' ? k : '', it.value] as [string, unknown];
+      });
+  }
+  if (isPlainObject(value)) return Object.entries(value);
+  return [];
+}
+
+function toRows(value: unknown, existingIds: string[]): Row[] {
   const ids = [...existingIds];
-  return Object.entries(obj).map(([key, value]) => {
+  return toEntries(value).map(([key, val]) => {
     const id = uniqueId('kv', ids);
     ids.push(id);
-    return { id, key, raw: toRaw(value) };
+    return { id, key, raw: toRaw(val) };
   });
 }
 
-/** Flush rows to an object, skipping empty/duplicate keys (first wins). */
-function rowsToObject(rows: Row[]): Record<string, unknown> {
+/** Flush rows back to the SAME shape, skipping empty/duplicate keys (first wins). */
+export function rowsToValue(
+  rows: Row[],
+  arrayShape: boolean,
+): Record<string, unknown> | Array<Record<string, unknown>> {
+  const seen = new Set<string>();
+  if (arrayShape) {
+    const list: Array<Record<string, unknown>> = [];
+    for (const r of rows) {
+      const k = r.key.trim();
+      if (!k || seen.has(k)) continue;
+      seen.add(k);
+      list.push({ variable: k, value: parseValue(r.raw) });
+    }
+    return list;
+  }
   const out: Record<string, unknown> = {};
   for (const r of rows) {
     const k = r.key.trim();
-    if (!k || k in out) continue;
+    if (!k || seen.has(k)) continue;
+    seen.add(k);
     out[k] = parseValue(r.raw);
   }
   return out;
 }
 
-function serialize(obj: Record<string, unknown>): string {
+/** Stable serialization for the resync guard (order-insensitive for objects). */
+function serialize(value: Record<string, unknown> | Array<Record<string, unknown>> | undefined): string {
+  if (Array.isArray(value)) return JSON.stringify(value);
+  const obj = value ?? {};
   const sorted = Object.keys(obj).sort().reduce<Record<string, unknown>>((acc, k) => {
     acc[k] = obj[k];
     return acc;
@@ -95,7 +132,7 @@ function serialize(obj: Record<string, unknown>): string {
 export interface FlowKeyValueFieldProps {
   label: string;
   value: unknown;
-  onCommit: (value: Record<string, unknown> | undefined) => void;
+  onCommit: (value: Record<string, unknown> | Array<Record<string, unknown>> | undefined) => void;
   disabled?: boolean;
   help?: string;
   addLabel: string;
@@ -120,24 +157,32 @@ export function FlowKeyValueField({
   emptyLabel,
   scopeGroups,
 }: FlowKeyValueFieldProps) {
-  const external = isPlainObject(value) ? value : {};
-  const [rows, setRows] = React.useState<Row[]>(() => toRows(external, []));
-  // Track the last value we committed so an external change (node switch) can
-  // resync rows without clobbering an in-progress edit of the same node.
-  const lastCommitted = React.useRef(serialize(external));
+  // Preserve whichever shape the value was authored in (object map vs the
+  // assignment-node array form) across edits.
+  const arrayShape = Array.isArray(value);
+  // Normalized serialization of the stored value — used only to detect an
+  // EXTERNAL change (node switch) that should resync the rows.
+  const external = React.useMemo(
+    () => serialize(rowsToValue(toRows(value, []), arrayShape)),
+    [value, arrayShape],
+  );
+  const [rows, setRows] = React.useState<Row[]>(() => toRows(value, []));
+  // Track the last value we committed so an external change can resync rows
+  // without clobbering an in-progress edit of the same node.
+  const lastCommitted = React.useRef(external);
 
   React.useEffect(() => {
-    const next = serialize(external);
-    if (next !== lastCommitted.current) {
-      setRows(toRows(external, []));
-      lastCommitted.current = next;
+    if (external !== lastCommitted.current) {
+      setRows(toRows(value, []));
+      lastCommitted.current = external;
     }
-  }, [external]);
+  }, [external, value]);
 
   const flush = (nextRows: Row[]) => {
-    const obj = rowsToObject(nextRows);
-    lastCommitted.current = serialize(obj);
-    onCommit(Object.keys(obj).length ? obj : undefined);
+    const out = rowsToValue(nextRows, arrayShape);
+    lastCommitted.current = serialize(out);
+    const empty = Array.isArray(out) ? out.length === 0 : Object.keys(out).length === 0;
+    onCommit(empty ? undefined : out);
   };
 
   const setRowField = (id: string, patch: Partial<Row>) => {

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

@@ -22,6 +22,7 @@ import { FlowReferenceField, type FlowReferenceContext } from './FlowReferenceFi
 import { validateExpressionClient } from './expression-validate';
 import { VariableTextInput } from './VariableTextInput';
 import type { ScopeGroup } from './useFlowScope';
+import { findUnknownRefs, scopeRoots, describeUnknownRefs } from './flow-ref-check';
 
 export interface FlowNodeConfigFieldProps {
   field: FlowConfigField;
@@ -36,6 +37,8 @@ export interface FlowNodeConfigFieldProps {
 }
 
 export function FlowNodeConfigField({ field, value, onCommit, disabled, locale, context, scopeGroups }: FlowNodeConfigFieldProps) {
+  const refMode: 'expression' | 'template' =
+    field.refMode ?? (field.kind === 'expression' ? 'expression' : 'template');
   const control = (() => {
     switch (field.kind) {
       case 'reference':
@@ -127,7 +130,7 @@ export function FlowNodeConfigField({ field, value, onCommit, disabled, locale,
             <VariableTextInput
               multiline
               rows={4}
-              mode="template"
+              mode={refMode}
               value={value != null ? String(value) : ''}
               onValueChange={(v) => onCommit(v)}
               groups={scopeGroups ?? []}
@@ -143,7 +146,7 @@ export function FlowNodeConfigField({ field, value, onCommit, disabled, locale,
           <div className="space-y-1">
             <Label className="text-xs text-muted-foreground">{field.label}</Label>
             <VariableTextInput
-              mode={field.kind === 'expression' ? 'expression' : 'template'}
+              mode={refMode}
               mono={field.kind === 'expression'}
               value={value != null ? String(value) : ''}
               onValueChange={(v) => onCommit(v)}
@@ -157,11 +160,26 @@ export function FlowNodeConfigField({ field, value, onCommit, disabled, locale,
   })();
 
   // ADR-0032 — surface a malformed condition (e.g. the `{record.x}` brace-in-CEL
-  // mistake) inline, as the author types, with the same corrective message the
-  // build and the agent tool emit. Only checked for expression-bearing fields.
+  // mistake) inline, with the same corrective message the build/agent emit. Only
+  // for expression fields (a genuine template uses single-brace `{var}` legally).
   const exprIssue =
     field.kind === 'expression' ? validateExpressionClient('predicate', value) : null;
 
+  // #1934 — pair the picker with a gentle, scope-aware "unknown reference"
+  // warning: CEL for expression fields, `{…}` holes for template fields. Skipped
+  // for free-form code (refMode 'expression' on a textarea, e.g. a script body)
+  // and when scope is unknown. The brace error above takes precedence.
+  const scopeRole: 'predicate' | 'template' | null =
+    field.kind === 'expression'
+      ? 'predicate'
+      : refMode === 'template' && (field.kind === 'text' || field.kind === 'textarea')
+        ? 'template'
+        : null;
+  const unknownRefs =
+    !exprIssue && scopeRole && scopeGroups && scopeGroups.length > 0
+      ? findUnknownRefs(value, scopeRole, scopeRoots(scopeGroups.flatMap((g) => g.refs)))
+      : [];
+
   return (
     <div className="space-y-1">
       {control}
@@ -170,7 +188,12 @@ export function FlowNodeConfigField({ field, value, onCommit, disabled, locale,
           {exprIssue.message}
         </p>
       )}
-      {field.help && !exprIssue && (
+      {!exprIssue && unknownRefs.length > 0 && (
+        <p className="text-[11px] leading-snug text-amber-600 dark:text-amber-400" role="note">
+          {describeUnknownRefs(unknownRefs)}
+        </p>
+      )}
+      {field.help && !exprIssue && unknownRefs.length === 0 && (
         <p className="text-[11px] leading-snug text-muted-foreground">{field.help}</p>
       )}
     </div>

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

@@ -147,6 +147,13 @@ export interface FlowConfigField {
   columns?: FlowConfigColumn[];
   /** Reference target for `reference` fields — drives the combobox data source. */
   ref?: FlowReferenceSpec;
+  /**
+   * Data-picker brace mode override (#1934). Defaults by kind (`expression` →
+   * bare CEL, `text` / `textarea` → `{var}` template). Set `'expression'` on a
+   * code field (e.g. a script body) so the picker inserts bare references, not
+   * `{var}` — `{x}` is a syntax error in a JS/TS script.
+   */
+  refMode?: 'expression' | 'template';
 }
 
 /** Convenience: a `['config', key]`-rooted field (the common case). */
@@ -327,6 +334,7 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
     cfg('script', 'Code', 'textarea', {
       placeholder: 'return { ok: true };',
       help: 'Script body (JS/TS).',
+      refMode: 'expression',
       showWhen: { field: 'actionType', equals: ['code'] },
     }),
     cfg('outputVariables', 'Output variables', 'stringList', {