@object-ui/app-shell 7.0.0 → 7.2.0

package/dist/views/metadata-admin/inspectors/datasetFilterCondition.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Bridge between the visual {@link FilterBuilder} (a flat `FilterGroup` of
+ * `{field, operator, value}` rows, camelCase operators) and the spec
+ * `FilterCondition` (Mongo-style `{ field: { $op: value } }`, conjoined with
+ * `$and`) stored on `dataset.filter` / `measure.filter`.
+ *
+ * Scope (deliberate): the visual editor supports the common case — a flat AND
+ * of simple `field op value` conditions. Anything it can't faithfully round-trip
+ * (nested groups, `$or`, multi-operator objects, unmapped operators) is reported
+ * as NOT representable so the caller can fall back to the source editor instead
+ * of silently corrupting the author's filter.
+ */
+/** FilterBuilder camelCase operator → FilterCondition Mongo operator. */
+const OP_TO_MONGO = {
+    equals: '$eq', notEquals: '$ne',
+    greaterThan: '$gt', greaterOrEqual: '$gte', lessThan: '$lt', lessOrEqual: '$lte',
+    after: '$gt', before: '$lt',
+    contains: '$contains', in: '$in', notIn: '$nin',
+};
+const MONGO_TO_OP = {
+    $eq: 'equals', $ne: 'notEquals',
+    $gt: 'greaterThan', $gte: 'greaterOrEqual', $lt: 'lessThan', $lte: 'lessOrEqual',
+    $contains: 'contains', $in: 'in', $nin: 'notIn',
+};
+/** Serialize the visual group → a spec FilterCondition (flat `$and`). */
+export function groupToCondition(group) {
+    const conds = (group?.conditions ?? []).filter((c) => c && c.field);
+    const parts = [];
+    for (const c of conds) {
+        if (c.operator === 'isEmpty') {
+            parts.push({ [c.field]: { $exists: false } });
+            continue;
+        }
+        if (c.operator === 'isNotEmpty') {
+            parts.push({ [c.field]: { $exists: true } });
+            continue;
+        }
+        const mop = OP_TO_MONGO[c.operator];
+        if (!mop)
+            continue; // unmapped (e.g. notContains/between) — drop rather than emit a bad filter
+        // Skip incomplete rows (no value typed yet) — emitting `{field:{$op:''}}` would
+        // be a silently-wrong filter (matches only empty), not "no filter".
+        const v = c.value;
+        if (v == null || v === '' || (Array.isArray(v) && v.length === 0))
+            continue;
+        parts.push({ [c.field]: { [mop]: v } });
+    }
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return { $and: parts };
+}
+/**
+ * Parse a stored FilterCondition → the visual group. `representable: false` when
+ * the condition uses shapes the flat builder can't faithfully edit (nested
+ * `$and`/`$or`, multi-op objects, unmapped operators) — callers should then show
+ * the source editor instead.
+ */
+export function conditionToGroup(cond) {
+    const empty = { id: 'g', logic: 'and', conditions: [] };
+    if (cond == null)
+        return { group: empty, representable: true };
+    if (typeof cond !== 'object' || Array.isArray(cond))
+        return { group: empty, representable: false };
+    if ('$or' in cond)
+        return { group: empty, representable: false };
+    const list = Array.isArray(cond.$and) ? cond.$and : [cond];
+    const conditions = [];
+    for (let i = 0; i < list.length; i++) {
+        const c = list[i];
+        if (!c || typeof c !== 'object' || Array.isArray(c))
+            return { group: empty, representable: false };
+        if ('$and' in c || '$or' in c)
+            return { group: empty, representable: false };
+        const keys = Object.keys(c);
+        if (keys.length !== 1)
+            return { group: empty, representable: false };
+        const field = keys[0];
+        const v = c[field];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const opKeys = Object.keys(v);
+            if (opKeys.length !== 1)
+                return { group: empty, representable: false };
+            const mop = opKeys[0];
+            if (mop === '$exists') {
+                conditions.push({ id: `c${i}`, field, operator: v.$exists ? 'isNotEmpty' : 'isEmpty', value: '' });
+            }
+            else {
+                const op = MONGO_TO_OP[mop];
+                if (!op)
+                    return { group: empty, representable: false };
+                conditions.push({ id: `c${i}`, field, operator: op, value: v[mop] });
+            }
+        }
+        else {
+            conditions.push({ id: `c${i}`, field, operator: 'equals', value: v }); // implicit equality
+        }
+    }
+    return { group: { id: 'g', logic: 'and', conditions }, representable: true };
+}

package/dist/views/metadata-admin/inspectors/flow-node-config.d.ts

@@ -93,6 +93,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;
@@ -120,10 +128,17 @@ 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';
 }
 /** Resolve the config fields for a node type (alias-aware). */
 export declare function fieldsForNodeType(type?: string): FlowConfigField[];
-/** 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 declare function getFieldValue(node: Record<string, unknown> | null | undefined, field: FlowConfigField): unknown;
 /**
  * The `config` key this field owns, or `undefined` for fields stored outside

package/dist/views/metadata-admin/inspectors/flow-node-config.js

@@ -40,10 +40,12 @@ const FLOW_NODE_CONFIG = {
             ref: { kind: 'object' },
             placeholder: 'crm_lead',
             help: 'Target object for record / scheduled-scan triggers.',
+            showWhen: { field: 'triggerType', equals: ['record-after-create', 'record-after-update', 'record-before-update', 'record-after-delete', 'record-change', 'schedule', 'webhook', 'event'] },
         }),
         cfg('condition', 'Entry condition', 'expression', {
             placeholder: 'status == "qualifying" && previous.status != "qualifying"',
             help: 'CEL predicate — the flow runs only when this is true. Leave empty to run on every event.',
+            showWhen: { field: 'triggerType', equals: ['record-after-create', 'record-after-update', 'record-before-update', 'record-after-delete', 'record-change', 'schedule', 'webhook', 'event'] },
         }),
         cfg('cron', 'Cron schedule', 'text', {
             placeholder: '0 7 * * *',
@@ -161,6 +163,7 @@ const FLOW_NODE_CONFIG = {
         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', {
@@ -169,9 +172,19 @@ const FLOW_NODE_CONFIG = {
         }),
         { id: 'timeoutMs', path: ['timeoutMs'], label: 'Timeout (ms)', kind: 'number', placeholder: '30000' },
     ],
+    // Screen — collect input (a flat `fields` list) OR render an object's full
+    // create/edit form (`objectName`, master-detail). `title`/`description`
+    // head the screen (description interpolates {var}); `waitForInput` forces a
+    // pause on a field-less message/confirmation screen. All optional and shown
+    // together so neither a message screen nor an object-form step needs JSON.
     screen: [
+        cfg('title', 'Title', 'text', { placeholder: 'Request a discount', help: 'Heading shown above the screen.' }),
+        cfg('description', 'Description', 'textarea', {
+            placeholder: 'Enter the deal amount and the discount you want.',
+            help: 'Body text. Interpolates {var} references (e.g. {approval_path}).',
+        }),
         cfg('fields', 'Fields', 'objectList', {
-            help: 'Fields presented on this screen.',
+            help: 'Input fields collected on this screen. Leave empty for a message-only screen.',
             columns: [
                 { key: 'name', label: 'Name', kind: 'text', placeholder: 'discount' },
                 { key: 'label', label: 'Label', kind: 'text', placeholder: 'Discount %' },
@@ -180,6 +193,29 @@ const FLOW_NODE_CONFIG = {
                 { key: 'visibleWhen', label: 'Visible when', kind: 'expression', placeholder: 'stage == "review"' },
             ],
         }),
+        cfg('waitForInput', 'Wait for input', 'boolean', {
+            help: 'Pause to show this screen even with no fields (a message / confirmation). A field-less screen with this off is a server pass-through.',
+        }),
+        cfg('objectName', 'Object form', 'reference', {
+            ref: { kind: 'object' },
+            placeholder: 'crm_account',
+            help: 'Render this object\u2019s full create/edit form (incl. master-detail) instead of a flat field list.',
+        }),
+        cfg('idVariable', 'Saved-record variable', 'text', {
+            placeholder: 'account_id',
+            help: 'Object form only: variable bound to the saved record\u2019s id, for later steps.',
+        }),
+        cfg('mode', 'Form mode', 'select', {
+            options: [
+                { value: 'create', label: 'Create' },
+                { value: 'edit', label: 'Edit' },
+            ],
+            defaultValue: 'create',
+            help: 'Object form only.',
+        }),
+        cfg('defaults', 'Form defaults', 'keyValue', {
+            help: 'Object form only: prefilled values (e.g. account \u2192 {account_id}).',
+        }),
     ],
     // Approval node (ADR-0019). The node opens an approval request on entry,
     // suspends the run, and resumes down its `approve` / `reject` out-edge once a
@@ -260,6 +296,15 @@ const FLOW_NODE_CONFIG = {
         },
         { id: 'escalation.escalateTo', path: ['config', 'escalation', 'escalateTo'], label: 'Escalate to', kind: 'reference', ref: { kind: 'role' }, placeholder: 'user id / role / manager level', showWhen: { field: 'escalation.enabled', equals: ['true'] } },
         { id: 'escalation.notifySubmitter', path: ['config', 'escalation', 'notifySubmitter'], label: 'Notify submitter', kind: 'boolean', showWhen: { field: 'escalation.enabled', equals: ['true'] } },
+        // ADR-0044 send-back-for-revision guard. Surfaces from the engine's
+        // published configSchema when online; this hardcoded copy keeps it visible
+        // offline / on an older backend. Only meaningful once the node has a
+        // `revise` out-edge (author one via the canvas "add revision loop").
+        cfg('maxRevisions', 'Max revisions', 'number', {
+            placeholder: '3',
+            defaultValue: '3',
+            help: 'Max send-backs for revision before the request auto-rejects (0 disables send-back). Needs a "revise" out-edge to take effect.',
+        }),
     ],
     wait: [
         at('waitEventConfig', 'eventType', 'Wait for', 'select', {
@@ -271,23 +316,27 @@ const FLOW_NODE_CONFIG = {
                 { 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: [
@@ -368,6 +417,7 @@ const FLOW_NODE_CONFIG = {
  */
 const TYPE_ALIASES = {
     action: 'legacy_action',
+    http: 'http_request',
     branch: 'decision',
     gateway: 'decision',
     condition: 'decision',
@@ -391,16 +441,22 @@ export function fieldsForNodeType(type) {
     const canonical = TYPE_ALIASES[type] ?? type;
     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, field) {
-    let cur = node;
-    for (const seg of field.path) {
-        if (cur && typeof cur === 'object' && !Array.isArray(cur))
-            cur = cur[seg];
-        else
-            return undefined;
-    }
-    return cur;
+    const read = (path) => {
+        let cur = node;
+        for (const seg of path) {
+            if (cur && typeof cur === 'object' && !Array.isArray(cur))
+                cur = cur[seg];
+            else
+                return undefined;
+        }
+        return cur;
+    };
+    const primary = read(field.path);
+    if (primary !== undefined)
+        return primary;
+    return field.fallbackPath ? read(field.fallbackPath) : undefined;
 }
 /**
  * The `config` key this field owns, or `undefined` for fields stored outside

package/dist/views/metadata-admin/inspectors/flow-ref-check.d.ts

@@ -0,0 +1,39 @@
+/**
+ * flow-ref-check — pure, scope-aware "unknown reference" detection for the flow
+ * inspector's inline validation (#1934 follow-up). Pairs the data-picker with a
+ * gentle warning when an authored expression / template references a name that
+ * is NOT in scope at the node — catching typos (`recrod.email`) and stale
+ * references the picker would have prevented.
+ *
+ * Deliberately conservative — a warning that cries wolf is worse than none:
+ *   • Only the ROOT of a reference path is checked (`record.email` → `record`),
+ *     so a field list is never needed; if `record` is in scope the whole path is
+ *     accepted.
+ *   • Function / macro calls (`daysFromNow(90)`, `has(...)`, `size(...)`) are
+ *     skipped — an identifier immediately followed by `(` is never a reference.
+ *   • String-literal contents are stripped before scanning.
+ *   • Runtime globals the engine injects (`env`, `$error`, `data`, …) and CEL
+ *     keywords/literals are allow-listed.
+ *   • For templates only the inside of single-brace `{…}` holes is scanned.
+ *
+ * The caller supplies the in-scope ROOT names (see {@link scopeRoots}); an empty
+ * set means "scope unknown" and the check is skipped (returns nothing).
+ */
+import type { ExprFieldRole } from './expression-validate';
+import type { ScopeRef } from './flow-scope';
+export interface UnknownRef {
+    /** The unresolved root identifier, as authored. */
+    token: string;
+    /** Nearest in-scope root within edit distance 2, when one exists (typo hint). */
+    suggestion?: string;
+}
+/** The set of valid root identifiers from a resolved scope's refs. */
+export declare function scopeRoots(refs: ReadonlyArray<ScopeRef>): Set<string>;
+/**
+ * Find referenced roots that are not in scope. Returns [] when clean, when the
+ * source is empty, or when `knownRoots` is empty (scope unknown → don't guess).
+ */
+export declare function findUnknownRefs(source: unknown, role: ExprFieldRole, knownRoots: Set<string>): UnknownRef[];
+/** Build a one-line inspector warning from unknown refs (shared by the field
+ *  and edge inspectors). */
+export declare function describeUnknownRefs(unknown: ReadonlyArray<UnknownRef>): string;

package/dist/views/metadata-admin/inspectors/flow-ref-check.js

@@ -0,0 +1,114 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/** CEL keywords / literals that are never flow references. */
+const CEL_RESERVED = new Set(['true', 'false', 'null', 'in']);
+/**
+ * Roots the engine provides at runtime that won't show up in the graph-resolved
+ * scope. Conservative allow-list — better to miss a typo than flag a valid ref.
+ */
+const RUNTIME_GLOBALS = new Set(['env', 'request', 'context', 'user', 'now', 'today', 'self', 'data']);
+/** The set of valid root identifiers from a resolved scope's refs. */
+export function scopeRoots(refs) {
+    const roots = new Set();
+    for (const r of refs) {
+        const root = r.token.split('.')[0];
+        if (root)
+            roots.add(root);
+    }
+    return roots;
+}
+/** Bounded Levenshtein distance, giving up (returns max+1) once it exceeds `max`. */
+function editDistance(a, b, max = 2) {
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    const prev = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        let rowMin = prev[0];
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = tmp;
+            if (prev[j] < rowMin)
+                rowMin = prev[j];
+        }
+        if (rowMin > max)
+            return max + 1;
+    }
+    return prev[b.length];
+}
+/** Extract reference-position root identifiers (skipping members and calls). */
+function rootIdentifiers(src) {
+    // Strip string literals so their contents aren't scanned as references.
+    const noStrings = src
+        .replace(/'(?:[^'\\]|\\.)*'/g, ' ')
+        .replace(/"(?:[^"\\]|\\.)*"/g, ' ');
+    const out = [];
+    // Lookbehind keeps this to ROOTS: an identifier not preceded by `.` (member),
+    // a word char, or `$`. Zero-width, so adjacent tokens are never swallowed.
+    const re = /(?<![.\w$])([A-Za-z_$][\w$]*)/g;
+    let m;
+    while ((m = re.exec(noStrings))) {
+        const name = m[1];
+        // A trailing `(` (after optional spaces) marks a function / macro call.
+        if (/^\s*\(/.test(noStrings.slice(m.index + name.length)))
+            continue;
+        if (CEL_RESERVED.has(name))
+            continue;
+        out.push(name);
+    }
+    return out;
+}
+/**
+ * Find referenced roots that are not in scope. Returns [] when clean, when the
+ * source is empty, or when `knownRoots` is empty (scope unknown → don't guess).
+ */
+export function findUnknownRefs(source, role, knownRoots) {
+    let raw = '';
+    if (typeof source === 'string')
+        raw = source;
+    else if (source && typeof source === 'object')
+        raw = String(source.source ?? '');
+    if (!raw.trim() || knownRoots.size === 0)
+        return [];
+    let scan = raw;
+    if (role === 'template') {
+        const holes = raw.match(/\{([^{}]+)\}/g);
+        if (!holes)
+            return [];
+        scan = holes.map((h) => h.slice(1, -1)).join(' ; ');
+    }
+    const seen = new Set();
+    const unknown = [];
+    for (const root of rootIdentifiers(scan)) {
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        if (knownRoots.has(root) || RUNTIME_GLOBALS.has(root) || root.startsWith('$'))
+            continue;
+        let suggestion;
+        let best = 3;
+        for (const k of knownRoots) {
+            const d = editDistance(root, k, 2);
+            if (d < best) {
+                best = d;
+                suggestion = k;
+            }
+        }
+        unknown.push({ token: root, suggestion: best <= 2 ? suggestion : undefined });
+    }
+    return unknown;
+}
+/** Build a one-line inspector warning from unknown refs (shared by the field
+ *  and edge inspectors). */
+export function describeUnknownRefs(unknown) {
+    if (unknown.length === 1) {
+        const u = unknown[0];
+        return u.suggestion
+            ? `Unknown reference \`${u.token}\` — did you mean \`${u.suggestion}\`?`
+            : `\`${u.token}\` is not a reference in scope at this step.`;
+    }
+    return `Not in scope: ${unknown.map((u) => `\`${u.token}\``).join(', ')}.`;
+}

package/dist/views/metadata-admin/inspectors/flow-scope.d.ts

@@ -0,0 +1,109 @@
+/**
+ * flow-scope — pure, framework-free resolution of the in-scope variable
+ * references at a given flow node, for the inspector's variable data-picker
+ * (#1934).
+ *
+ * "In scope" is GRAPH-AWARE: a reference is offered at node N only if it can
+ * actually exist when N runs. Concretely:
+ *
+ *   - Flow variables — every entry in `draft.variables[]` (declared up-front, so
+ *     always in scope).
+ *   - Upstream outputs — the `outputVariable(s)` / collected screen
+ *     `fields[].name` / `assignments` keys / `idVariable` of every ANCESTOR node
+ *     (a node from which N is reachable, found by walking edges backwards). A
+ *     node's OWN outputs and any DOWNSTREAM node's outputs are deliberately
+ *     excluded — they don't exist yet when N runs. This is the property the
+ *     picker's "a downstream output is not offered upstream" guarantee rests on.
+ *   - Loop / map iterators — the `iteratorVariable` of an enclosing loop/map
+ *     ancestor, surfaced as its own group.
+ *   - Trigger record — on a record-triggered flow, the trigger object's fields.
+ *     Referenced BARE on the start node's own entry condition (`status`,
+ *     matching the engine's trigger-evaluation context where the changed
+ *     record's fields are top-level) and as `record.<field>` on every
+ *     downstream node (the convention the showcase flows use). The object's
+ *     field list is fetched lazily by the React layer (see useFlowScope); this
+ *     module only resolves the object NAME and the correct token prefix.
+ *
+ * The graph-walk here is the unit-tested heart of the picker; async field-list
+ * expansion and rendering live in the React layer so this module stays pure.
+ */
+/** Which group a reference belongs to (drives the picker's section headers). */
+export type ScopeGroupId = 'variables' | 'outputs' | 'loop' | 'trigger';
+/**
+ * One pickable reference. `token` is the BARE form (no braces); the picker
+ * inserts it as-is into CEL `expression` fields and wraps it as `{token}` for
+ * `text` / `textarea` template fields (ADR-0032 — the brace rule is handled for
+ * the author).
+ */
+export interface ScopeRef {
+    token: string;
+    /** Primary display text (the token, or the bare field name). */
+    label: string;
+    /** Secondary, muted text — a type, an origin node label, etc. */
+    detail?: string;
+    group: ScopeGroupId;
+}
+/** The trigger object whose fields the UI layer should fetch and expand. */
+export interface TriggerScope {
+    objectName: string;
+    /** Per-field token prefix: '' on the start node (bare), 'record.' downstream. */
+    fieldPrefix: string;
+    /** Also emit `previous.<field>` refs (update / change / before-update triggers). */
+    includePrevious: boolean;
+}
+export interface FlowScope {
+    /**
+     * References resolvable WITHOUT a network fetch: flow variables, upstream
+     * outputs, loop iterators, and the whole-record `record` / `previous` tokens.
+     */
+    refs: ScopeRef[];
+    /** Present when a record trigger is in scope — the UI expands its fields. */
+    trigger?: TriggerScope;
+}
+interface FlowNodeLike {
+    id?: unknown;
+    type?: unknown;
+    label?: unknown;
+    config?: unknown;
+}
+interface FlowEdgeLike {
+    source?: unknown;
+    target?: unknown;
+}
+/**
+ * Ancestor node ids of `nodeId` — every node from which `nodeId` is reachable
+ * by following edges forward (equivalently, a reverse breadth-first walk from
+ * `nodeId`). Cycle-safe (a declared `back`-edge revise loop won't spin) and
+ * never includes `nodeId` itself.
+ */
+export declare function flowAncestors(nodeId: string, edges: FlowEdgeLike[]): Set<string>;
+/**
+ * The variable names a node INTRODUCES into scope for its successors — mirroring
+ * what the simulator (flow-simulator.ts) and engine actually write:
+ * `outputVariable` (single), `outputVariables` (list), an assignment node's
+ * `assignments` keys (map / array / flat shapes), a screen's collected
+ * `fields[].name`, a screen object-form's `idVariable`, and a loop/map
+ * `iteratorVariable` (flagged as a `loop` ref). The start node is NOT handled
+ * here — its trigger record is resolved separately.
+ */
+export declare function nodeOutputRefs(node: FlowNodeLike): ScopeRef[];
+/**
+ * Resolve the in-scope reference set at `nodeId` (graph-aware). Pure: the
+ * trigger object's fields are NOT expanded here (that needs an async fetch) —
+ * the returned `trigger` carries the object name and per-field token prefix for
+ * the UI layer to expand. Order: flow variables, upstream outputs, loop
+ * iterators, then trigger refs, de-duplicated by token.
+ */
+export declare function resolveFlowScope(draft: Record<string, unknown>, nodeId: string | undefined): FlowScope;
+/**
+ * Expand a trigger object's fields into per-field refs — `record.<field>`
+ * downstream, bare `<field>` on the start node — given an already-fetched field
+ * list. Split out from {@link resolveFlowScope} so it is unit-testable without a
+ * metadata client.
+ */
+export declare function triggerFieldRefs(trigger: TriggerScope, fields: ReadonlyArray<{
+    name: string;
+    label?: string;
+    type?: string;
+}>): ScopeRef[];
+export {};