@object-ui/app-shell 7.1.0 → 7.2.0

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 {};

package/dist/views/metadata-admin/inspectors/flow-scope.js

@@ -0,0 +1,199 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/** Trigger types that fire on a single record (so `record` is in scope). */
+const RECORD_TRIGGER_TYPES = new Set([
+    'record-after-create',
+    'record-after-update',
+    'record-before-update',
+    'record-after-delete',
+    'record-change',
+]);
+/** Trigger types that carry a meaningful `previous` snapshot of the record. */
+const PREVIOUS_TRIGGER_TYPES = new Set([
+    'record-after-update',
+    'record-before-update',
+    'record-change',
+]);
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function asRecord(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function str(v) {
+    return typeof v === 'string' && v ? v : undefined;
+}
+/**
+ * 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 function flowAncestors(nodeId, edges) {
+    const rev = new Map();
+    for (const e of edges) {
+        const s = str(e.source);
+        const t = str(e.target);
+        if (!s || !t)
+            continue;
+        const list = rev.get(t);
+        if (list)
+            list.push(s);
+        else
+            rev.set(t, [s]);
+    }
+    const seen = new Set();
+    const stack = [...(rev.get(nodeId) ?? [])];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (cur === nodeId || seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const p of rev.get(cur) ?? [])
+            stack.push(p);
+    }
+    return seen;
+}
+/**
+ * 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 function nodeOutputRefs(node) {
+    const type = str(node.type);
+    const cfg = asRecord(node.config);
+    const nodeId = str(node.id) ?? '';
+    const label = str(node.label);
+    const detail = label && label !== nodeId ? label : nodeId || undefined;
+    const out = [];
+    const add = (token, group = 'outputs') => {
+        if (token && !out.some((r) => r.token === token)) {
+            out.push({ token, label: token, detail, group });
+        }
+    };
+    // Loop / map iterator — its own group.
+    if (type === 'loop' || type === 'map')
+        add(str(cfg.iteratorVariable), 'loop');
+    // Single + multi output variables (create/get/http/subflow/map/end/script).
+    add(str(cfg.outputVariable));
+    for (const name of asArray(cfg.outputVariables))
+        add(str(name));
+    // Screen object-form: the saved record's id is bound to a variable.
+    add(str(cfg.idVariable));
+    // Assignment node — the assigned variable names. Accepts the three authoring
+    // shapes the simulator/engine accept: an array of `{variable|name|key}`, a
+    // flat `{ var: value }` map, or (legacy) keys directly on config.
+    if (type === 'assignment') {
+        const raw = cfg.assignments;
+        if (Array.isArray(raw)) {
+            for (const item of raw) {
+                const e = asRecord(item);
+                add(str(e.variable) ?? str(e.name) ?? str(e.key));
+            }
+        }
+        else if (raw && typeof raw === 'object') {
+            for (const k of Object.keys(raw))
+                add(k);
+        }
+    }
+    // Screen — collected input field names become variables for downstream nodes.
+    if (type === 'screen' || type === 'user_task') {
+        for (const f of asArray(cfg.fields))
+            add(str(asRecord(f).name));
+    }
+    return out;
+}
+/** De-duplicate by token, keeping the first (group-priority) occurrence. */
+function dedupeByToken(refs) {
+    const seen = new Set();
+    return refs.filter((r) => (seen.has(r.token) ? false : (seen.add(r.token), true)));
+}
+/**
+ * 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 function resolveFlowScope(draft, nodeId) {
+    const nodes = asArray(draft.nodes).map(asRecord);
+    const edges = asArray(draft.edges);
+    const refs = [];
+    // 1. Flow variables — always in scope (declared up-front).
+    for (const v of asArray(draft.variables)) {
+        const rec = asRecord(v);
+        const name = str(rec.name);
+        if (!name)
+            continue;
+        const type = str(rec.type);
+        refs.push({ token: name, label: name, detail: type ? `variable · ${type}` : 'variable', group: 'variables' });
+    }
+    if (!nodeId)
+        return { refs: dedupeByToken(refs) };
+    // 2. Upstream outputs + loop iterators — from ANCESTOR nodes only.
+    const ancestors = flowAncestors(nodeId, edges);
+    const startNode = nodes.find((n) => str(n.type) === 'start');
+    const startId = str(startNode?.id);
+    for (const node of nodes) {
+        const id = str(node.id);
+        if (!id || id === nodeId || !ancestors.has(id))
+            continue;
+        if (id === startId)
+            continue; // the start node contributes the trigger record, below
+        for (const ref of nodeOutputRefs(node))
+            refs.push(ref);
+    }
+    // 3. Trigger record — on a record-triggered flow, when the start node is in
+    //    scope: either we ARE the start node (editing its own entry condition) or
+    //    the start node is an ancestor (it is the ancestor of everything reachable).
+    if (startNode) {
+        const cfg = asRecord(startNode.config);
+        const triggerType = str(cfg.triggerType);
+        const objectName = str(cfg.objectName);
+        const isRecordTrigger = !!triggerType && RECORD_TRIGGER_TYPES.has(triggerType);
+        const startInScope = startId === nodeId || (!!startId && ancestors.has(startId));
+        if (isRecordTrigger && objectName && startInScope) {
+            const onStart = startId === nodeId;
+            const includePrevious = PREVIOUS_TRIGGER_TYPES.has(triggerType);
+            // On the start node the record's fields ARE the bare evaluation context
+            // (`status`), so the whole record is not a named ref there; `previous` is
+            // (`previous.status`). Downstream the record is the named `record` object.
+            if (!onStart) {
+                refs.push({ token: 'record', label: 'record', detail: `trigger record · ${objectName}`, group: 'trigger' });
+            }
+            if (includePrevious) {
+                refs.push({ token: 'previous', label: 'previous', detail: 'record values before the change', group: 'trigger' });
+            }
+            return { refs: dedupeByToken(refs), trigger: { objectName, fieldPrefix: onStart ? '' : 'record.', includePrevious } };
+        }
+    }
+    return { refs: dedupeByToken(refs) };
+}
+/**
+ * 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 function triggerFieldRefs(trigger, fields) {
+    const out = [];
+    for (const f of fields) {
+        if (!f?.name)
+            continue;
+        const token = `${trigger.fieldPrefix}${f.name}`;
+        const detail = f.label && f.label !== f.name ? f.label : f.type;
+        out.push({ token, label: token, detail, group: 'trigger' });
+        if (trigger.includePrevious) {
+            out.push({
+                token: `previous.${f.name}`,
+                label: `previous.${f.name}`,
+                detail: detail ? `prior ${detail}` : 'prior value',
+                group: 'trigger',
+            });
+        }
+    }
+    return out;
+}

package/dist/views/metadata-admin/inspectors/useDatasetFields.d.ts

@@ -46,10 +46,21 @@ export interface NormalizedObject {
 /** Normalize a raw object metadata doc into label + fields + relationships. */
 export declare function normalizeObject(doc: Record<string, unknown> | null | undefined, name: string): NormalizedObject;
 /**
- * Build the flat `field` / `relationship.field` option list from the base
- * object and the included relationships' (already-fetched) target objects.
+ * Walk a dotted relationship PATH from the base object, returning the object at
+ * its end (whose fields a `path.field` references) plus each hop's relationship
+ * label, or undefined if any hop can't be resolved (ADR-0071 multi-hop).
+ * `objectsByName` holds the already-fetched objects along the chain.
  */
-export declare function buildFieldOptions(base: NormalizedObject, include: string[], targets: Record<string, NormalizedObject>): DatasetFieldOption[];
+export declare function resolvePath(base: NormalizedObject, path: string, objectsByName: Record<string, NormalizedObject>): {
+    target: NormalizedObject;
+    labels: string[];
+} | undefined;
+/**
+ * Build the flat `field` / `relationship[.relationship].field` option list from
+ * the base object and the (already-fetched) objects along each included PATH.
+ * Single-hop paths behave exactly as before.
+ */
+export declare function buildFieldOptions(base: NormalizedObject, include: string[], objectsByName: Record<string, NormalizedObject>): DatasetFieldOption[];
 /** Recursively test whether a metadata doc references `datasetName` via a `dataset` key. */
 export declare function referencesDataset(doc: unknown, datasetName: string): boolean;
 /** Every object as `{ name, label }`, sorted by label. Fetched once. */

package/dist/views/metadata-admin/inspectors/useFlowScope.d.ts

@@ -0,0 +1,23 @@
+import { type ScopeGroupId, type ScopeRef } from './flow-scope';
+export interface ScopeGroup {
+    id: ScopeGroupId;
+    label: string;
+    refs: ScopeRef[];
+}
+export interface UseFlowScopeResult {
+    /** Non-empty groups, in display order. */
+    groups: ScopeGroup[];
+    /** Flat, de-duplicated ref list (all groups). */
+    refs: ScopeRef[];
+    /** True while the trigger object's fields are still loading. */
+    loading: boolean;
+    /** No references in scope — the field should render as a plain input. */
+    isEmpty: boolean;
+}
+/**
+ * Resolve + (async) expand the in-scope references at a flow node. `draft` is
+ * the whole flow draft; `nodeId` the node being edited (for an edge, pass its
+ * source node id — references available on an edge are those in scope at its
+ * source).
+ */
+export declare function useFlowScope(draft: Record<string, unknown> | undefined, nodeId: string | undefined): UseFlowScopeResult;

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

@@ -0,0 +1,45 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * useFlowScope — React adapter over the pure {@link resolveFlowScope} graph-walk
+ * that powers the inspector's variable data-picker (#1934).
+ *
+ * It resolves the graph-aware refs synchronously, then lazily fetches the
+ * trigger object's field catalog (via the shared metadata client) and merges
+ * the expanded `record.<field>` refs in — grouping everything into the ordered
+ * sections the picker renders. An empty result (`isEmpty`) tells the field to
+ * degrade to a plain input.
+ */
+import * as React from 'react';
+import { resolveFlowScope, triggerFieldRefs, } from './flow-scope';
+import { useObjectFields } from '../previews/useObjectFields';
+const GROUP_ORDER = ['variables', 'outputs', 'loop', 'trigger'];
+const GROUP_LABELS = {
+    variables: 'Flow variables',
+    outputs: 'Upstream outputs',
+    loop: 'Loop item',
+    trigger: 'Trigger record',
+};
+/**
+ * Resolve + (async) expand the in-scope references at a flow node. `draft` is
+ * the whole flow draft; `nodeId` the node being edited (for an edge, pass its
+ * source node id — references available on an edge are those in scope at its
+ * source).
+ */
+export function useFlowScope(draft, nodeId) {
+    const scope = React.useMemo(() => resolveFlowScope(draft ?? {}, nodeId), [draft, nodeId]);
+    const { fields, loading } = useObjectFields(scope.trigger?.objectName);
+    return React.useMemo(() => {
+        const all = [...scope.refs];
+        if (scope.trigger)
+            all.push(...triggerFieldRefs(scope.trigger, fields));
+        // Global de-dup by token (a declared var also written upstream shows once).
+        const seen = new Set();
+        const refs = all.filter((r) => (seen.has(r.token) ? false : (seen.add(r.token), true)));
+        const groups = GROUP_ORDER.map((id) => ({
+            id,
+            label: GROUP_LABELS[id],
+            refs: refs.filter((r) => r.group === id),
+        })).filter((g) => g.refs.length > 0);
+        return { groups, refs, loading: !!scope.trigger && loading, isEmpty: refs.length === 0 };
+    }, [scope, fields, loading]);
+}

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

@@ -24,3 +24,18 @@ export declare function buildPackageScopeOptions(rawList: unknown[] | null | und
     id: string;
     name: string;
 }[];
+/**
+ * True for the runtime/null "Local / Custom" sentinel scope. Per ADR-0070 D5
+ * this is a *migration* surface (move loose items into a base), never a valid
+ * create destination — callers gate "create" on a real writable base.
+ */
+export declare function isLocalScope(id: string | null | undefined): boolean;
+/**
+ * The writable bases (project-scoped DB packages) from the raw package list —
+ * the only valid authoring destinations (ADR-0070 D2). Excludes code/installed
+ * (system|cloud) packages AND the Local sentinel.
+ */
+export declare function writableBaseOptions(rawList: unknown[] | null | undefined): {
+    id: string;
+    name: string;
+}[];

package/dist/views/metadata-admin/package-scope.js

@@ -41,3 +41,19 @@ export function buildPackageScopeOptions(rawList) {
     // preserved; the user opts into the local scope explicitly.
     return [...opts, { id: LOCAL_PACKAGE_ID, name: t('engine.package.local', detectLocale()) }];
 }
+/**
+ * True for the runtime/null "Local / Custom" sentinel scope. Per ADR-0070 D5
+ * this is a *migration* surface (move loose items into a base), never a valid
+ * create destination — callers gate "create" on a real writable base.
+ */
+export function isLocalScope(id) {
+    return !id || id === LOCAL_PACKAGE_ID;
+}
+/**
+ * The writable bases (project-scoped DB packages) from the raw package list —
+ * the only valid authoring destinations (ADR-0070 D2). Excludes code/installed
+ * (system|cloud) packages AND the Local sentinel.
+ */
+export function writableBaseOptions(rawList) {
+    return buildPackageScopeOptions(rawList).filter((o) => o.id !== LOCAL_PACKAGE_ID);
+}

package/dist/views/metadata-admin/preview-registry.d.ts

@@ -84,6 +84,18 @@ export interface MetadataPreviewProps {
      * "click widget → edit widget in the right panel" pattern.
      */
     onSelectionChange?: (selection: MetadataSelection | null) => void;
+    /**
+     * Optional: server-computed validation diagnostics for the current draft
+     * (the layered record's `_diagnostics`, kept in sync with live client-side
+     * issues). Each entry carries a dotted JSON path so a preview can map it onto
+     * the offending sub-element. Used by the flow preview's Problems panel +
+     * on-canvas badges; ignored by previews that don't surface diagnostics.
+     */
+    diagnostics?: Array<{
+        path?: string;
+        message: string;
+        severity?: 'error' | 'warning';
+    }>;
 }
 export type MetadataPreview = ComponentType<MetadataPreviewProps>;
 /**

package/dist/views/metadata-admin/previews/FlowCanvas.d.ts

@@ -20,6 +20,7 @@
  */
 import * as React from 'react';
 import { type FlowNode, type FlowEdge } from './flow-canvas-layout';
+import { type FlowProblem } from './flow-problems';
 export interface FlowCanvasProps {
     nodes: FlowNode[];
     edges: FlowEdge[];
@@ -39,11 +40,29 @@ export interface FlowCanvasProps {
     invalidNodeIds?: string[];
     /** Structural-validation: edges (keyed `${source}->${target}`) to paint red. */
     invalidEdges?: ReadonlySet<string>;
-    /** Structural-validation error messages shown in an inline canvas banner. */
-    validationErrors?: string[];
+    /**
+     * Select + reveal a problem when its inline-banner row is clicked — wired to
+     * the same handler the Problems panel uses, so the always-visible banner is
+     * actionable without opening the panel.
+     */
+    onRevealProblem?: (problem: FlowProblem) => void;
+    /**
+     * Unified validation issues (structural + server) rendered as per-element
+     * badges; the Problems panel shares the same list.
+     */
+    problems?: FlowProblem[];
+    /**
+     * Imperative "reveal" request from the Problems panel: when `nonce` changes
+     * the canvas pans to center the targeted node/edge. Selection highlight is
+     * driven separately via `selectedId` / `selectedEdgeId`.
+     */
+    revealSignal?: {
+        target: FlowProblem['target'];
+        nonce: number;
+    } | null;
     onSelect: (node: FlowNode | null) => void;
     /** Select an edge (its `edgeKey`), or clear selection with `null`. */
     onSelectEdge?: (edge: FlowEdge | null, key: string) => void;
     onPatch?: (partial: Record<string, unknown>) => void;
 }
-export declare function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, invalidNodeIds, invalidEdges, validationErrors, onSelect, onSelectEdge, onPatch, }: FlowCanvasProps): React.JSX.Element;
+export declare function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, invalidNodeIds, invalidEdges, onRevealProblem, problems, revealSignal, onSelect, onSelectEdge, onPatch, }: FlowCanvasProps): React.JSX.Element;