@nocobase/plugin-flow-engine 2.1.0-beta.37 → 2.1.0-beta.40

package/dist/server/flow-surfaces/service.js

@@ -42,6 +42,7 @@ module.exports = __toCommonJS(service_exports);
 var import_crypto = require("crypto");
 var import_utils = require("@nocobase/utils");
 var import_lodash = __toESM(require("lodash"));
+var antDesignIconAsn = __toESM(require("@ant-design/icons-svg"));
 var import_repository = __toESM(require("../repository"));
 var import_catalog = require("./catalog");
 var import_action_scope = require("./action-scope");
@@ -102,6 +103,56 @@ var import_template_service_utils = require("./template-service-utils");
 var import_hidden_popup_contract = require("./hidden-popup-contract");
 var import_hidden_popup_calendar = require("./hidden-popup-calendar");
 var import_hidden_popup_kanban = require("./hidden-popup-kanban");
+const FLOW_SURFACE_CHART_REPAIR_HINT = "This is a chart payload shape problem. Repair the current chart block payload using assets.charts.<key>.query/visual plus block.chart, or localized settings.query/settings.visual. Do not change this block type to table, jsBlock, actionPanel, gridCard, or another block type. Do not drop or defer the chart. KPI / summary numbers should use jsBlock; charts are for trends, distributions, rankings, and visual analysis.";
+const FLOW_SURFACE_CHART_REPAIR_STEPS = [
+  "Keep the block type as chart.",
+  "Define assets.charts.<key>.query and assets.charts.<key>.visual, or repair the localized settings.query/settings.visual on the existing chart block.",
+  "Reference the asset from the chart block with block.chart = <key> when using assets.charts.",
+  "Retry the chart payload instead of replacing the chart with another block type, omitting it, or deferring it."
+];
+const FLOW_SURFACE_CHART_EXPECTED_SHAPE = {
+  assets: {
+    charts: {
+      chartKey: {
+        query: "builder/sql query configuration",
+        visual: "basic/custom visual configuration"
+      }
+    }
+  },
+  block: {
+    type: "chart",
+    chart: "chartKey"
+  }
+};
+const FLOW_SURFACE_CHART_FORBIDDEN_FALLBACKS = [
+  "table",
+  "jsBlock",
+  "actionPanel",
+  "gridCard",
+  "drop chart",
+  "defer chart"
+];
+function withChartRepairMessage(message) {
+  return `${message}. ${FLOW_SURFACE_CHART_REPAIR_HINT}`;
+}
+function withFlowSurfaceChartRepairDetails(details = {}) {
+  return {
+    ...details,
+    repairHint: FLOW_SURFACE_CHART_REPAIR_HINT,
+    repairSteps: FLOW_SURFACE_CHART_REPAIR_STEPS,
+    expectedShape: FLOW_SURFACE_CHART_EXPECTED_SHAPE,
+    forbiddenFallbacks: FLOW_SURFACE_CHART_FORBIDDEN_FALLBACKS
+  };
+}
+function throwChartRepairBadRequest(message, details = {}) {
+  (0, import_errors.throwBadRequest)(withChartRepairMessage(message), {
+    details: withFlowSurfaceChartRepairDetails(details)
+  });
+}
+function isFlowSurfaceChartRepairError(error) {
+  var _a, _b;
+  return error instanceof import_errors.FlowSurfaceBadRequestError && ((_b = (_a = error.options) == null ? void 0 : _a.details) == null ? void 0 : _b.repairHint) === FLOW_SURFACE_CHART_REPAIR_HINT;
+}
 const FORM_BLOCK_USES = /* @__PURE__ */ new Set(["FormBlockModel", "CreateFormModel", "EditFormModel", ...import_approval.APPROVAL_FORM_BLOCK_USES]);
 const AUTO_SUBMIT_FORM_BLOCK_USES = /* @__PURE__ */ new Set(["CreateFormModel", "EditFormModel"]);
 const FLOW_SURFACE_DEFAULT_ACTION_SETTINGS_KEYS = /* @__PURE__ */ new Set(["filter"]);
@@ -251,6 +302,17 @@ const JS_ACTION_USES = /* @__PURE__ */ new Set([
   "JSActionModel"
 ]);
 const JS_ITEM_ACTION_USES = /* @__PURE__ */ new Set(["JSItemActionModel"]);
+const JS_POPUP_GUIDANCE_MESSAGE = "should use ctx.openView to open popup";
+const JS_POPUP_GUIDANCE_USES = /* @__PURE__ */ new Set([
+  ...JS_ACTION_USES,
+  ...JS_ITEM_ACTION_USES,
+  "JSColumnModel",
+  "JSItemModel",
+  "JSFieldModel",
+  "JSEditableFieldModel",
+  "FormJSFieldItemModel"
+]);
+const JS_POPUP_GUIDANCE_PUBLIC_KEYS = /* @__PURE__ */ new Set(["js", "jsColumn", "jsItem"]);
 const POPUP_ACTION_USES = /* @__PURE__ */ new Set([
   "AddNewActionModel",
   "ViewActionModel",
@@ -264,6 +326,24 @@ const POPUP_ACTION_USES = /* @__PURE__ */ new Set([
   "AddChildActionModel",
   "MailSendActionModel"
 ]);
+function withJsPopupGuidance(message, value) {
+  const normalizedValue = String(value || "").trim();
+  if (JS_POPUP_GUIDANCE_USES.has(normalizedValue) || JS_POPUP_GUIDANCE_PUBLIC_KEYS.has(normalizedValue)) {
+    return `${message}; ${JS_POPUP_GUIDANCE_MESSAGE}`;
+  }
+  return message;
+}
+function assertNoJsDeclarativeOpenView(context, changes, use) {
+  const normalizedUse = String(use || "").trim();
+  if ((0, import_service_utils.hasOwnDefined)(changes, "openView") && JS_POPUP_GUIDANCE_USES.has(normalizedUse)) {
+    (0, import_errors.throwBadRequest)(
+      withJsPopupGuidance(
+        `flowSurfaces configure ${context} '${normalizedUse}' does not support openView`,
+        normalizedUse
+      )
+    );
+  }
+}
 const POPUP_HOST_DEFAULT_RECORD_CONTEXT_ACTION_USES = /* @__PURE__ */ new Set([
   "ViewActionModel",
   "EditActionModel",
@@ -457,6 +537,7 @@ const UPDATE_SETTINGS_STEP_PARAM_MIRRORS_BY_USE = {
   DividerItemModel: DIVIDER_ITEM_STEP_PARAM_MIRRORS
 };
 const FLOW_SURFACE_MENU_BINDABLE_OPTION_KEY = "flowSurfaceMenuBindable";
+const ANT_DESIGN_ICON_NAMES = new Set(Object.keys(antDesignIconAsn || {}));
 const AI_EMPLOYEE_ACTION_USE = "AIEmployeeButtonModel";
 const AI_EMPLOYEE_OWNER_PLUGIN = "@nocobase/plugin-ai";
 const AI_EMPLOYEE_PUBLIC_SETTING_KEYS = ["username", "auto", "workContext", "tasks", "style"];
@@ -464,10 +545,13 @@ const AI_EMPLOYEE_INTERNAL_PROP_KEYS = ["aiEmployee", "context", "auto", "tasks"
 const AI_EMPLOYEE_TASK_STEP_PARAMS_PATH = ["shortcutSettings", "editTasks", "tasks"];
 const AI_EMPLOYEE_WORK_CONTEXT_PUBLIC_KEYS = ["type", "uid", "target"];
 const AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS = ["title", "message", "autoSend", "skillSettings", "model", "webSearch"];
+const AI_EMPLOYEE_TASK_PATCH_PUBLIC_SETTING_KEYS = [...AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS, "prompt"];
 const AI_EMPLOYEE_TASK_MESSAGE_PUBLIC_KEYS = ["system", "user", "workContext"];
 const AI_EMPLOYEE_TASK_MODEL_PUBLIC_KEYS = ["llmService", "model"];
 const AI_EMPLOYEE_SKILL_SETTINGS_PUBLIC_KEYS = ["skills", "tools", "skillsVersion", "toolsVersion"];
 const AI_EMPLOYEE_STYLE_PUBLIC_KEYS = ["size", "mask"];
+const AI_EMPLOYEE_WORK_CONTEXT_REPAIR_HINT = 'Use workContext entries like { "target": "self" } or { "uid": "<flow-model-uid>" }. The only supported type is flow-model, so type is optional and defaults to flow-model.';
+const AI_EMPLOYEE_TASK_REPAIR_HINT = "Use task keys title, message, prompt, autoSend, skillSettings, model, and webSearch. Put user instructions in tasks[n].message.user or the prompt alias; do not write raw props, stepParams, or prompt beside message.user.";
 const AI_EMPLOYEE_PROMPT_CONTEXT_MAX_DEPTH = 8;
 const AI_EMPLOYEE_PROMPT_VARIABLE_INVALID = "FLOW_SURFACE_AI_EMPLOYEE_PROMPT_VARIABLE_INVALID";
 const AI_EMPLOYEE_CURRENT_RECORD_PROMPT_VARIABLE = "{{ ctx.record }}";
@@ -773,6 +857,18 @@ class FlowSurfacesService {
       })
     );
   }
+  routeParentIdMatches(routeParentId, parentId) {
+    if (import_lodash.default.isNil(routeParentId) && import_lodash.default.isNil(parentId)) {
+      return true;
+    }
+    return String(routeParentId ?? "") === String(parentId ?? "");
+  }
+  async findMenuGroupRoutesByParentIdAndTitle(parentId, title, transaction) {
+    const routes = await this.findMenuGroupRoutesByTitle(title, transaction);
+    return routes.filter(
+      (route) => this.routeParentIdMatches(this.readRouteField(route, "parentId") ?? null, parentId)
+    );
+  }
   async findFlowPageRoutesByParentIdAndTitle(parentId, title, transaction) {
     const normalizedTitle = String(title || "").trim();
     const normalizedParentId = String(parentId ?? "").trim();
@@ -854,20 +950,97 @@ class FlowSurfacesService {
       ...extras
     };
   }
+  isValidMenuIconName(value) {
+    const normalized = String(value || "").trim();
+    return !!normalized && ANT_DESIGN_ICON_NAMES.has(normalized);
+  }
+  assertVisibleNavigationIcon(actionName, path, values) {
+    if (values.hideInMenu === true) {
+      return;
+    }
+    const icon = String(values.icon || "").trim();
+    if (!icon) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${path}.icon is required when creating a visible menu route`, {
+        ruleId: "navigation-icon-required",
+        path: `${path}.icon`,
+        details: {
+          repairHint: "Pass a valid Ant Design icon name such as AppstoreOutlined, DashboardOutlined, or FolderOpenOutlined."
+        }
+      });
+    }
+    if (!this.isValidMenuIconName(icon)) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${path}.icon must be a valid Ant Design icon name`, {
+        ruleId: "navigation-icon-unknown",
+        path: `${path}.icon`,
+        details: {
+          icon
+        }
+      });
+    }
+  }
+  assertVisibleNavigationRouteIconUpdate(actionName, path, route, values) {
+    if (!Object.prototype.hasOwnProperty.call(values, "icon") || this.readRouteField(route, "hideInMenu") === true) {
+      return;
+    }
+    const icon = String(values.icon || "").trim();
+    if (!icon) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${path}.icon cannot be empty for a visible menu route`, {
+        ruleId: "navigation-icon-required",
+        path: `${path}.icon`,
+        details: {
+          repairHint: "Pass a valid Ant Design icon name such as AppstoreOutlined, DashboardOutlined, or FolderOpenOutlined."
+        }
+      });
+    }
+    if (!this.isValidMenuIconName(icon)) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${path}.icon must be a valid Ant Design icon name`, {
+        ruleId: "navigation-icon-unknown",
+        path: `${path}.icon`,
+        details: {
+          icon
+        }
+      });
+    }
+  }
   async createFlowMenuGroup(values, transaction) {
     const parentRoute = await this.assertMenuParentIsGroup(values.parentMenuRouteId, transaction);
+    const parentId = this.readRouteField(parentRoute, "id") ?? null;
+    const title = String(values.title || "").trim();
+    const existingGroups = await this.findMenuGroupRoutesByParentIdAndTitle(parentId, title, transaction);
+    if (existingGroups.length === 1) {
+      return this.buildMenuResult(existingGroups[0]);
+    }
+    if (existingGroups.length > 1) {
+      (0, import_errors.throwBadRequest)(
+        `flowSurfaces createMenu group title '${title}' is ambiguous under parentMenuRouteId '${values.parentMenuRouteId ?? "root"}'; use an explicit existing navigation.group.routeId or clean up duplicate menu groups before retrying`,
+        {
+          ruleId: "menu-group-title-ambiguous-under-parent",
+          details: {
+            title,
+            parentMenuRouteId: values.parentMenuRouteId ?? null,
+            matches: existingGroups.map((route2) => ({
+              routeId: this.readRouteField(route2, "id"),
+              parentMenuRouteId: this.readRouteField(route2, "parentId") ?? null,
+              type: this.readRouteField(route2, "type"),
+              schemaUid: this.readRouteField(route2, "schemaUid") ?? null
+            }))
+          }
+        }
+      );
+    }
+    this.assertVisibleNavigationIcon("createMenu", "values", values);
     const schemaUid = values.schemaUid || (0, import_utils.uid)();
     const desktopRoutes = this.db.getRepository("desktopRoutes");
     await desktopRoutes.create({
       values: {
         type: "group",
         sort: this.allocateRouteSortValue(),
-        title: values.title,
+        title,
         icon: values.icon,
         tooltip: values.tooltip,
         schemaUid,
         hideInMenu: !!values.hideInMenu,
-        parentId: this.readRouteField(parentRoute, "id") ?? null
+        parentId
       },
       transaction
     });
@@ -880,6 +1053,7 @@ class FlowSurfacesService {
   async createFlowMenuItem(values, transaction) {
     var _a;
     const parentRoute = await this.assertMenuParentIsGroup(values.parentMenuRouteId, transaction);
+    this.assertVisibleNavigationIcon("createMenu", "values", values);
     const pageSchemaUid = values.pageSchemaUid || (0, import_utils.uid)();
     const pageUid = values.pageUid || (0, import_utils.uid)();
     const tabSchemaUid = values.tabSchemaUid || (0, import_utils.uid)();
@@ -2607,6 +2781,10 @@ class FlowSurfacesService {
       ),
       options.transaction
     );
+    if (!(rawNode == null ? void 0 : rawNode.uid)) {
+      const resolvedUid = String((resolved == null ? void 0 : resolved.uid) || "").trim() || String(target.uid || target.tabSchemaUid || target.pageSchemaUid || target.routeId || "").trim() || "unknown";
+      (0, import_errors.throwBadRequest)(`flowSurfaces:get target '${resolvedUid}' could not resolve a readable surface tree`);
+    }
     const publicNode = this.stripInternalSurfaceMetaFromNodeTree(import_lodash.default.cloneDeep(rawNode));
     return this.buildSurfaceReadPayload(target, resolved, publicNode, options);
   }
@@ -2778,13 +2956,13 @@ class FlowSurfacesService {
     if (!groupTitle) {
       return document;
     }
-    const matchedRoutes = await this.findMenuGroupRoutesByTitle(groupTitle, transaction);
+    const matchedRoutes = await this.findMenuGroupRoutesByParentIdAndTitle(null, groupTitle, transaction);
     if (!matchedRoutes.length) {
       return document;
     }
     if (matchedRoutes.length > 1) {
       (0, import_errors.throwBadRequest)(
-        `flowSurfaces applyBlueprint navigation.group.title '${groupTitle}' matches ${matchedRoutes.length} existing menu groups; pass navigation.group.routeId explicitly`
+        `flowSurfaces applyBlueprint navigation.group.title '${groupTitle}' matches ${matchedRoutes.length} existing root menu groups; pass navigation.group.routeId explicitly`
       );
     }
     const routeId = this.readRouteField(matchedRoutes[0], "id");
@@ -3332,6 +3510,12 @@ class FlowSurfacesService {
       options
     );
     const pageLocator = (0, import_blueprint.resolveApplyBlueprintPageLocator)(prepared, result);
+    await this.ensureSurfaceTableDefaultActionIntegrity(pageLocator, {
+      ...options,
+      enabledPackages: await this.resolveEnabledPluginPackages(options),
+      popupTemplateAliasSession,
+      popupTemplateTreeCache
+    });
     if (resultOptions.readSurface === false) {
       return {
         version: "1",
@@ -4008,8 +4192,8 @@ class FlowSurfacesService {
       stepParams: (0, import_template_service_utils.buildFlowTemplateReferenceBlockStepParams)(template, templateTargetUid, init)
     };
   }
-  buildPopupTemplateReferenceOpenView(template, templateTargetUid) {
-    return this.buildPopupTemplateOpenView(template, "reference", templateTargetUid);
+  buildPopupTemplateReferenceOpenView(template, templateTargetUid, options = {}) {
+    return this.buildPopupTemplateOpenView(template, "reference", templateTargetUid, options);
   }
   shouldHydrateDetachedPopupTemplateBlockResourceContext(blockNode, context) {
     if (!this.isCollectionBlockUse(blockNode == null ? void 0 : blockNode.use) || !context.associationName || !context.sourceId) {
@@ -4359,15 +4543,35 @@ class FlowSurfacesService {
     }
     const nextStepParams = import_lodash.default.cloneDeep(sourceNode.stepParams || {});
     const currentGroup = import_lodash.default.isPlainObject(nextStepParams[openViewStep.flowKey]) ? import_lodash.default.cloneDeep(nextStepParams[openViewStep.flowKey]) : {};
+    const popupProfile = await this.resolvePopupBlockProfile(sourceNode.uid, null, sourceNode, transaction).catch(
+      () => null
+    );
+    const useRuntimeRecordFilterByTk = (popupProfile == null ? void 0 : popupProfile.hasCurrentRecord) === true;
+    const filterTargetKey = useRuntimeRecordFilterByTk ? await this.resolveOpenViewRuntimeRecordFilterTargetKey(openViewStep.openView, template, {
+      transaction,
+      popupTemplateHostUid: sourceNode.uid,
+      popupActionContext: {
+        hasCurrentRecord: true
+      }
+    }) : void 0;
+    const currentOpenView = import_lodash.default.omit(openViewStep.openView || {}, [
+      "popupTemplateUid",
+      "popupTemplateMode",
+      "popupTemplateContext",
+      "popupTemplateHasFilterByTk",
+      "popupTemplateHasSourceId"
+    ]);
+    if (useRuntimeRecordFilterByTk && this.shouldOmitRuntimeRecordFilterByTk(currentOpenView.filterByTk, {
+      filterTargetKey
+    })) {
+      delete currentOpenView.filterByTk;
+    }
     let nextOpenView = {
-      ...import_lodash.default.omit(openViewStep.openView || {}, [
-        "popupTemplateUid",
-        "popupTemplateMode",
-        "popupTemplateContext",
-        "popupTemplateHasFilterByTk",
-        "popupTemplateHasSourceId"
-      ]),
-      ...this.buildPopupTemplateReferenceOpenView(template, templateTargetUid)
+      ...currentOpenView,
+      ...this.buildPopupTemplateReferenceOpenView(template, templateTargetUid, {
+        filterTargetKey,
+        useRuntimeRecordFilterByTk
+      })
     };
     if (String(sourceNode.use || "").trim() === "AddChildActionModel") {
       nextOpenView = await this.normalizeAddChildOpenViewForAction(sourceNode, nextOpenView, transaction);
@@ -5109,6 +5313,13 @@ class FlowSurfacesService {
     });
     for (const [blockIndex, block] of result.blocks.entries()) {
       const blockSpec = normalizedBlocks.find((item) => item.key === block.key);
+      if ((blockSpec == null ? void 0 : blockSpec.type) === "table") {
+        await this.ensureTableDefaultActionIntegrity(block.uid, {
+          ...runtimeOptions,
+          enabledPackages,
+          popupTemplateAliasSession
+        });
+      }
       if ((blockSpec == null ? void 0 : blockSpec.type) === "table") {
         const appliedTreeTableDefaults = await this.applyTreeTableCreatedBlockDefaults(
           {
@@ -5242,7 +5453,7 @@ class FlowSurfacesService {
       if ((current == null ? void 0 : current.use) === "DividerItemModel") {
         return this.configureDividerItem(target, changes, options);
       }
-      return this.configureJSItem(target, changes, options);
+      return this.configureJSItem(target, changes, { ...options, currentUse: (current == null ? void 0 : current.use) || "JSItemModel" });
     }
     if ((0, import_service_utils.isFieldNodeUse)(current == null ? void 0 : current.use)) {
       return this.configureFieldNode(target, changes, configureOptions);
@@ -5317,6 +5528,7 @@ class FlowSurfacesService {
     if (!this.isBindableMenuRoutePendingInitialization(route, structure)) {
       (0, import_errors.throwBadRequest)(`flowSurfaces createPage does not allow re-initializing menu route '${routeId}'`);
     }
+    this.assertVisibleNavigationRouteIconUpdate("createPage", "values", route, values);
     const existingPage = structure.pageModel;
     const enableTabs = !!values.enableTabs;
     const displayTitle = values.displayTitle !== false;
@@ -6396,7 +6608,7 @@ class FlowSurfacesService {
         key: String((values == null ? void 0 : values.key) || catalogItem.key || (values == null ? void 0 : values.type) || (values == null ? void 0 : values.use) || "addBlock_inline").trim() || "addBlock_inline",
         type: catalogItem.key || values.type,
         fields: values.fields,
-        fieldsLayout: values.fieldsLayout
+        ...Object.prototype.hasOwnProperty.call(values || {}, "fieldsLayout") ? { fieldsLayout: values.fieldsLayout } : {}
       },
       0,
       enabledPackages,
@@ -6590,6 +6802,8 @@ class FlowSurfacesService {
             ...fieldSpec.popupSize ? { popupSize: fieldSpec.popupSize } : {},
             ...!import_lodash.default.isUndefined(fieldSpec.pageSize) ? { pageSize: fieldSpec.pageSize } : {},
             ...!import_lodash.default.isUndefined(fieldSpec.showIndex) ? { showIndex: fieldSpec.showIndex } : {},
+            ...fieldSpec.defaultTargetUid ? { defaultTargetUid: fieldSpec.defaultTargetUid } : {},
+            ...fieldSpec.targetBlockUid ? { targetBlockUid: fieldSpec.targetBlockUid } : {},
             ...fieldSpec.popup ? { popup: fieldSpec.popup } : {},
             ...fieldSpec.__autoPopupForRelationField ? { __autoPopupForRelationField: true } : {},
             ...fieldSpec[import_defaults.FLOW_SURFACE_APPLY_BLUEPRINT_POPUP_DEFAULTS_KEY] ? {
@@ -6664,6 +6878,13 @@ class FlowSurfacesService {
         enabledPackages
       }
     );
+    if (catalogItem.use === "TableBlockModel" && !options.skipDefaultBlockActions) {
+      await this.ensureTableDefaultActionIntegrity(created, {
+        ...options,
+        enabledPackages,
+        popupTemplateTreeCache: options.popupTemplateTreeCache
+      });
+    }
     if (!options.deferAutoLayout && (initialGrid == null ? void 0 : initialGrid.uid)) {
       const finalGrid = await this.repository.findModelById(parentUid, {
         transaction: options.transaction,
@@ -6731,7 +6952,9 @@ class FlowSurfacesService {
         (0, import_errors.throwBadRequest)("flowSurfaces fieldType is only supported for relation fields");
       }
       if (inlinePopup) {
-        (0, import_errors.throwBadRequest)(`flowSurfaces addField type '${values.type}' does not support popup`);
+        (0, import_errors.throwBadRequest)(
+          withJsPopupGuidance(`flowSurfaces addField type '${values.type}' does not support popup`, values.type)
+        );
       }
       if (isFilterFormItem) {
         (0, import_errors.throwBadRequest)(`flowSurfaces addField type '${values.type}' is not allowed under filter-form`);
@@ -6926,9 +7149,18 @@ class FlowSurfacesService {
       }
     }
     if (inlinePopup && !this.isPopupFieldHostUse(boundFieldCapability.fieldUse)) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces addField field '${boundFieldCapability.fieldUse}' does not support popup`);
+      (0, import_errors.throwBadRequest)(
+        withJsPopupGuidance(
+          `flowSurfaces addField field '${boundFieldCapability.fieldUse}' does not support popup`,
+          boundFieldCapability.fieldUse
+        )
+      );
     }
-    if (values.__autoPopupForRelationField === true && !inlinePopup && this.isPopupFieldHostUse(boundFieldCapability.fieldUse) && ((0, import_service_helpers.isAssociationField)(resolvedField.field) || !!normalizedFieldBinding.associationPathName) && !this.peekInlineFieldSettingsOpenView(inlineSettings, boundFieldCapability.wrapperUse)) {
+    const inlineSettingsOpenView = this.peekInlineFieldSettingsOpenView(
+      inlineSettings,
+      boundFieldCapability.wrapperUse
+    );
+    if (values.__autoPopupForRelationField === true && !inlinePopup && this.isPopupFieldHostUse(boundFieldCapability.fieldUse) && ((0, import_service_helpers.isAssociationField)(resolvedField.field) || !!normalizedFieldBinding.associationPathName) && !inlineSettingsOpenView) {
       const popupDefaultsMetadata = values[import_defaults.FLOW_SURFACE_APPLY_BLUEPRINT_POPUP_DEFAULTS_KEY];
       inlinePopup = this.normalizeInlinePopup("addField", {
         tryTemplate: true,
@@ -6938,9 +7170,19 @@ class FlowSurfacesService {
         } : {}
       });
     }
-    if (inlinePopup && this.isExternalPopupOpenView(
-      this.peekInlineFieldSettingsOpenView(inlineSettings, boundFieldCapability.wrapperUse)
-    )) {
+    const hasExternalInlineSettingsOpenView = this.isExternalPopupOpenView(inlineSettingsOpenView);
+    if (!inlinePopup && this.isPopupFieldHostUse(boundFieldCapability.fieldUse) && !hasExternalInlineSettingsOpenView && (this.isInlineFieldClickToOpenEnabled(inlineSettings, boundFieldCapability.wrapperUse) || import_lodash.default.isPlainObject(inlineSettingsOpenView))) {
+      const popupDefaultsMetadata = values[import_defaults.FLOW_SURFACE_APPLY_BLUEPRINT_POPUP_DEFAULTS_KEY];
+      inlinePopup = this.normalizeInlinePopup("addField", {
+        tryTemplate: true,
+        defaultType: "view",
+        ...import_lodash.default.isPlainObject(inlineSettingsOpenView) ? { openView: import_lodash.default.cloneDeep(inlineSettingsOpenView) } : {},
+        ...popupDefaultsMetadata ? {
+          [import_defaults.FLOW_SURFACE_APPLY_BLUEPRINT_POPUP_DEFAULTS_KEY]: popupDefaultsMetadata
+        } : {}
+      });
+    }
+    if (inlinePopup && hasExternalInlineSettingsOpenView) {
       (0, import_errors.throwBadRequest)(`flowSurfaces addField popup cannot be combined with external openView.uid`);
     }
     const defaultFieldState = (0, import_service_utils.buildDefaultFieldState)(
@@ -7079,7 +7321,12 @@ class FlowSurfacesService {
       );
     }
     if (inlinePopup && !POPUP_ACTION_USES.has(actionCatalogItem.use)) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces addAction type '${actionCatalogItem.key}' does not support popup`);
+      (0, import_errors.throwBadRequest)(
+        withJsPopupGuidance(
+          `flowSurfaces addAction type '${actionCatalogItem.key}' does not support popup`,
+          actionCatalogItem.key
+        )
+      );
     }
     await this.assertApprovalActionSingleton(container.parentUid, actionCatalogItem.use, options.transaction);
     (0, import_action_scope.assertRequestedActionScope)({
@@ -7129,6 +7376,12 @@ class FlowSurfacesService {
         actionSettingsPayload,
         aiEmployeeSettingsPayload
       );
+      await this.assertNoDuplicateAIEmployeeAction(
+        "addAction",
+        container.parentUid,
+        actionSettingsPayload,
+        options.transaction
+      );
     }
     const action = (0, import_builder.buildActionTree)({
       use: actionCatalogItem.use,
@@ -7191,7 +7444,12 @@ class FlowSurfacesService {
     );
     const resolvedScope = actionCatalogItem.scope;
     if (inlinePopup && !POPUP_ACTION_USES.has(actionCatalogItem.use)) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces addRecordAction type '${actionCatalogItem.key}' does not support popup`);
+      (0, import_errors.throwBadRequest)(
+        withJsPopupGuidance(
+          `flowSurfaces addRecordAction type '${actionCatalogItem.key}' does not support popup`,
+          actionCatalogItem.key
+        )
+      );
     }
     if (this.isAddChildCatalogItem(actionCatalogItem)) {
       await this.assertAddChildSupportedForOwnerNode(container.ownerNode, "addRecordAction", options.transaction);
@@ -7245,6 +7503,12 @@ class FlowSurfacesService {
         actionSettingsPayload,
         aiEmployeeSettingsPayload
       );
+      await this.assertNoDuplicateAIEmployeeAction(
+        "addRecordAction",
+        materializedContainer.parentUid,
+        actionSettingsPayload,
+        options.transaction
+      );
     }
     const action = (0, import_builder.buildActionTree)({
       use: actionCatalogItem.use,
@@ -8181,6 +8445,17 @@ class FlowSurfacesService {
     const { fieldChanges } = (0, import_service_utils.splitComposeFieldChanges)(settings, wrapperUse);
     return fieldChanges.openView;
   }
+  isInlineFieldClickToOpenEnabled(settings, wrapperUse) {
+    if (!settings || !Object.keys(settings).length) {
+      return false;
+    }
+    const { fieldChanges } = (0, import_service_utils.splitComposeFieldChanges)(settings, wrapperUse);
+    if (!Object.prototype.hasOwnProperty.call(fieldChanges, "clickToOpen")) {
+      return false;
+    }
+    const value = fieldChanges.clickToOpen;
+    return value === true || import_lodash.default.isPlainObject(value) && value.clickToOpen === true;
+  }
   async assertOpenViewUidTarget(actionName, uid2, options = {}) {
     const targetNode = await this.repository.findModelById(uid2, {
       transaction: options.transaction,
@@ -8711,15 +8986,71 @@ class FlowSurfacesService {
       sourceId: String(template.sourceId || "").trim() || void 0
     };
   }
-  buildPopupTemplateOpenView(template, mode, uidValue) {
+  shouldUseRuntimeRecordFilterByTkForOpenView(openView, options = {}) {
+    var _a;
+    return !!String((openView == null ? void 0 : openView.popupTemplateUid) || "").trim() && ((_a = options.popupActionContext) == null ? void 0 : _a.hasCurrentRecord) === true;
+  }
+  resolveOpenViewFilterTargetKey(openView, template) {
+    const dataSourceKey = String((openView == null ? void 0 : openView.dataSourceKey) || (template == null ? void 0 : template.dataSourceKey) || "main").trim() || "main";
+    const collectionName = String((openView == null ? void 0 : openView.collectionName) || (template == null ? void 0 : template.collectionName) || "").trim();
+    const collection = collectionName ? this.getCollection(dataSourceKey, collectionName) : null;
+    return this.getCollectionFilterTargetKey(collection);
+  }
+  async resolvePopupHostCurrentRecordFilterTargetKey(hostUid, transaction) {
+    var _a, _b, _c;
+    const normalizedHostUid = String(hostUid || "").trim();
+    if (!normalizedHostUid) {
+      return void 0;
+    }
+    const hostNode = await this.repository.findModelById(normalizedHostUid, {
+      transaction,
+      includeAsyncNode: true
+    }).catch(() => null);
+    if (!(hostNode == null ? void 0 : hostNode.uid)) {
+      return void 0;
+    }
+    const hostContext = await this.resolvePopupHostProfileContext(hostNode, transaction).catch(() => null);
+    const ownerResourceInit = ((_a = hostContext == null ? void 0 : hostContext.resourceContext) == null ? void 0 : _a.resourceInit) || {};
+    const dataSourceKey = String(((_b = hostContext == null ? void 0 : hostContext.associationContext) == null ? void 0 : _b.dataSourceKey) || ownerResourceInit.dataSourceKey || "main").trim() || "main";
+    const collectionName = String(
+      ((_c = hostContext == null ? void 0 : hostContext.associationContext) == null ? void 0 : _c.collectionName) || ownerResourceInit.collectionName || ""
+    ).trim();
+    const collection = collectionName ? this.getCollection(dataSourceKey, collectionName) : null;
+    return collection ? this.getCollectionFilterTargetKey(collection) : void 0;
+  }
+  async resolveOpenViewRuntimeRecordFilterTargetKey(openView, template, options = {}) {
+    var _a;
+    const contextKey = String(((_a = options.popupActionContext) == null ? void 0 : _a.currentRecordFilterTargetKey) || "").trim();
+    if (contextKey) {
+      return contextKey;
+    }
+    const hostKey = await this.resolvePopupHostCurrentRecordFilterTargetKey(
+      options.popupTemplateHostUid,
+      options.transaction
+    );
+    return hostKey || this.resolveOpenViewFilterTargetKey(openView, template);
+  }
+  shouldOmitRuntimeRecordFilterByTk(value, options = {}) {
+    const normalized = this.normalizeFlowContextTemplateValue(value);
+    if (!normalized) {
+      return false;
+    }
+    if (normalized === "{{ctx.view.inputArgs.filterByTk}}") {
+      return true;
+    }
+    const filterTargetKey = String(options.filterTargetKey || "").trim();
+    return !!filterTargetKey && normalized === `{{ctx.record.${filterTargetKey}}}`;
+  }
+  buildPopupTemplateOpenView(template, mode, uidValue, options = {}) {
     const popupTemplateHasFilterByTk = !!String(template.filterByTk || "").trim();
     const popupTemplateHasSourceId = !!String(template.sourceId || "").trim() || !!String(template.associationName || "").trim();
+    const omitRuntimeRecordFilterByTk = options.useRuntimeRecordFilterByTk === true && this.shouldOmitRuntimeRecordFilterByTk(template.filterByTk, { filterTargetKey: options.filterTargetKey });
     const base = (0, import_service_utils.buildDefinedPayload)({
       uid: uidValue,
       dataSourceKey: template.dataSourceKey,
       collectionName: template.collectionName,
       associationName: template.associationName,
-      ...popupTemplateHasFilterByTk ? { filterByTk: template.filterByTk } : {},
+      ...popupTemplateHasFilterByTk && !omitRuntimeRecordFilterByTk ? { filterByTk: template.filterByTk } : {},
       ...popupTemplateHasSourceId && template.sourceId ? { sourceId: template.sourceId } : {},
       popupTemplateHasFilterByTk,
       popupTemplateHasSourceId,
@@ -8792,7 +9123,7 @@ class FlowSurfacesService {
     }
   }
   async normalizeOpenView(actionName, openView, options = {}) {
-    var _a;
+    var _a, _b, _c, _d;
     if (import_lodash.default.isUndefined(openView) || import_lodash.default.isNull(openView)) {
       return openView;
     }
@@ -8859,17 +9190,39 @@ class FlowSurfacesService {
       if (templateRef.mode === "copy") {
         await this.ensurePopupSurface(resolvedUid, options.transaction);
       }
-      let nextTemplateOpenView = this.buildPopupTemplateOpenView(template, templateRef.mode, resolvedUid);
+      let runtimeRecordFilterTargetKey;
+      if (((_b = options.popupActionContext) == null ? void 0 : _b.hasCurrentRecord) === true) {
+        runtimeRecordFilterTargetKey = await this.resolveOpenViewRuntimeRecordFilterTargetKey(
+          normalizedOpenView,
+          template,
+          options
+        );
+      }
+      const filterTargetKey = runtimeRecordFilterTargetKey || this.resolveOpenViewFilterTargetKey(normalizedOpenView, template);
+      let nextTemplateOpenView = this.buildPopupTemplateOpenView(template, templateRef.mode, resolvedUid, {
+        filterTargetKey,
+        useRuntimeRecordFilterByTk: ((_c = options.popupActionContext) == null ? void 0 : _c.hasCurrentRecord) === true
+      });
       Object.keys(normalizedOpenView).forEach((key) => {
         if (key === "template" || key === "popupTemplateUid" || key === "popupTemplateMode" || key === "popupTemplateContext" || key === "popupTemplateHasFilterByTk" || key === "popupTemplateHasSourceId") {
           delete normalizedOpenView[key];
         }
       });
+      if (((_d = options.popupActionContext) == null ? void 0 : _d.hasCurrentRecord) === true && this.shouldOmitRuntimeRecordFilterByTk(normalizedOpenView.filterByTk, {
+        filterTargetKey
+      })) {
+        delete normalizedOpenView.filterByTk;
+      }
       if (String(options.popupTemplateHostUse || "").trim() === "AddChildActionModel") {
         nextTemplateOpenView = import_lodash.default.omit(nextTemplateOpenView, ["sourceId"]);
       }
       Object.assign(normalizedOpenView, nextTemplateOpenView);
     }
+    if (this.shouldUseRuntimeRecordFilterByTkForOpenView(normalizedOpenView, options) && this.shouldOmitRuntimeRecordFilterByTk(normalizedOpenView.filterByTk, {
+      filterTargetKey: await this.resolveOpenViewRuntimeRecordFilterTargetKey(normalizedOpenView, void 0, options)
+    })) {
+      delete normalizedOpenView.filterByTk;
+    }
     if (!import_lodash.default.isUndefined(normalizedOpenView.uid)) {
       const normalizedUid = String(normalizedOpenView.uid || "").trim();
       if (!normalizedUid) {
@@ -8910,7 +9263,8 @@ class FlowSurfacesService {
       return void 0;
     }
     return {
-      hasCurrentRecord: true
+      hasCurrentRecord: true,
+      currentRecordFilterTargetKey: await this.resolvePopupHostCurrentRecordFilterTargetKey(current.uid, transaction)
     };
   }
   unsetPayloadPathAndPruneEmptyParents(payload, path) {
@@ -9068,7 +9422,12 @@ class FlowSurfacesService {
       return {};
     }
     if (input.popup && !this.isPopupFieldHostUse(fieldNode.use)) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} field '${fieldNode.use}' does not support popup`);
+      (0, import_errors.throwBadRequest)(
+        withJsPopupGuidance(
+          `flowSurfaces ${actionName} field '${fieldNode.use}' does not support popup`,
+          fieldNode.use
+        )
+      );
     }
     let openView = this.resolvePopupHostOpenView(fieldNode);
     if (input.popup && this.isExternalPopupOpenView(openView, fieldHostUid)) {
@@ -9394,6 +9753,20 @@ class FlowSurfacesService {
   isEmptyInlinePopupPayload(popup) {
     return import_lodash.default.isPlainObject(popup) && Object.keys(popup).length === 0;
   }
+  isInlineFieldPopupDefaultShell(popup) {
+    if (!import_lodash.default.isPlainObject(popup)) {
+      return false;
+    }
+    const shellOnlyKeys = /* @__PURE__ */ new Set([
+      "title",
+      "mode",
+      "openView",
+      "tryTemplate",
+      "defaultType",
+      import_defaults.FLOW_SURFACE_APPLY_BLUEPRINT_POPUP_DEFAULTS_KEY
+    ]);
+    return Object.keys(popup).every((key) => shellOnlyKeys.has(key));
+  }
   shouldAutoCompleteDefaultFieldPopup(fieldNode, popup, wrapperNode) {
     if (!import_lodash.default.isPlainObject(popup)) {
       return false;
@@ -9408,7 +9781,7 @@ class FlowSurfacesService {
     if (!String(fieldContext.collectionName || "").trim()) {
       return false;
     }
-    return popup.tryTemplate === true || !import_lodash.default.isUndefined(popup.defaultType) || Object.keys(popup).length === 0;
+    return popup.tryTemplate === true || !import_lodash.default.isUndefined(popup.defaultType) || this.isInlineFieldPopupDefaultShell(popup);
   }
   isInlineFieldPopupBlockMissingResource(block) {
     if (!import_lodash.default.isPlainObject(block) || !import_lodash.default.isUndefined(block.template)) {
@@ -10470,14 +10843,21 @@ class FlowSurfacesService {
       actionNode,
       options.transaction
     ).catch(() => null);
-    const filterTargetKey = (popupProfile == null ? void 0 : popupProfile.currentCollection) ? this.getCollectionFilterTargetKey(popupProfile.currentCollection) : null;
+    const useRuntimeRecordFilterByTk = this.isReferencedPopupTemplateOpenView(currentOpenView, actionNode.uid);
+    const filterTargetKey = useRuntimeRecordFilterByTk ? await this.resolveOpenViewRuntimeRecordFilterTargetKey(currentOpenView, void 0, {
+      transaction: options.transaction,
+      popupTemplateHostUid: actionNode.uid,
+      popupActionContext: {
+        hasCurrentRecord: true
+      }
+    }) : (popupProfile == null ? void 0 : popupProfile.currentCollection) ? this.getCollectionFilterTargetKey(popupProfile.currentCollection) : null;
     const defaultFilterByTk = this.resolvePopupCurrentRecordResourceFilterByTk(popupProfile);
     const currentFilterByTk = import_lodash.default.isString(currentOpenView.filterByTk) ? currentOpenView.filterByTk.trim() : "";
-    const preserveCustomFilterByTk = currentFilterByTk && currentFilterByTk !== "{{ctx.view.inputArgs.filterByTk}}" && currentFilterByTk !== (filterTargetKey ? `{{ctx.record.${filterTargetKey}}}` : "");
+    const preserveCustomFilterByTk = currentFilterByTk && !this.shouldOmitRuntimeRecordFilterByTk(currentOpenView.filterByTk, { filterTargetKey: filterTargetKey || "" });
     const nextOpenView = (0, import_service_utils.buildDefinedPayload)({
-      ...currentOpenView,
+      ...useRuntimeRecordFilterByTk && !preserveCustomFilterByTk ? import_lodash.default.omit(currentOpenView, ["filterByTk"]) : currentOpenView,
       title: openViewTitle,
-      filterByTk: preserveCustomFilterByTk ? currentOpenView.filterByTk : defaultFilterByTk || currentOpenView.filterByTk
+      filterByTk: useRuntimeRecordFilterByTk ? preserveCustomFilterByTk ? currentOpenView.filterByTk : void 0 : preserveCustomFilterByTk ? currentOpenView.filterByTk : defaultFilterByTk || currentOpenView.filterByTk
     });
     if (import_lodash.default.isEqual(nextOpenView, currentOpenView)) {
       return;
@@ -11700,7 +12080,12 @@ class FlowSurfacesService {
     }
     if (!((_c = sqlPreview.queryOutputs) == null ? void 0 : _c.length)) {
       (0, import_errors.throwBadRequest)(
-        "chart visual.mode='basic' requires previewable SQL query outputs; write query first, then read flowSurfaces:context(path='chart'), or use visual.mode='custom' after browser verification"
+        withChartRepairMessage(
+          "chart visual.mode='basic' requires previewable SQL query outputs; write query first, then read flowSurfaces:context(path='chart'), or use visual.mode='custom' after browser verification"
+        ),
+        {
+          details: withFlowSurfaceChartRepairDetails()
+        }
       );
     }
     const supportedOutputs = new Set(
@@ -11709,7 +12094,14 @@ class FlowSurfacesService {
     for (const mappingField of (0, import_chart_config.getChartVisualMappingAliases)(state.visual)) {
       if (!supportedOutputs.has(mappingField)) {
         (0, import_errors.throwBadRequest)(
-          `chart visual mappings only support SQL query output fields: ${Array.from(supportedOutputs).join(", ")}`
+          withChartRepairMessage(
+            `chart visual mappings only support SQL query output fields: ${Array.from(supportedOutputs).join(", ")}`
+          ),
+          {
+            details: withFlowSurfaceChartRepairDetails({
+              supportedOutputs: Array.from(supportedOutputs)
+            })
+          }
         );
       }
     }
@@ -11758,13 +12150,32 @@ class FlowSurfacesService {
           continue;
         }
         (0, import_errors.throwBadRequest)(
-          `flowSurfaces ${actionName} ${item.path} '${fieldPath}' does not exist on collection '${dataSourceKey}.${collectionName}'`
+          withChartRepairMessage(
+            `flowSurfaces ${actionName} ${item.path} '${fieldPath}' does not exist on collection '${dataSourceKey}.${collectionName}'`
+          ),
+          {
+            details: withFlowSurfaceChartRepairDetails({
+              fieldPath,
+              dataSourceKey,
+              collectionName
+            })
+          }
         );
       }
       if (!fieldPath.includes(".") && (0, import_service_helpers.isAssociationField)(field)) {
         const suggestion = this.resolveBuilderChartAssociationSubfieldSuggestion(fieldPath, field, dataSourceKey);
         (0, import_errors.throwBadRequest)(
-          `flowSurfaces ${actionName} ${item.path} '${fieldPath}' references an association field directly; use scalar subfield '${suggestion.suggestedFieldPath}' for builder charts`
+          withChartRepairMessage(
+            `flowSurfaces ${actionName} ${item.path} '${fieldPath}' references an association field directly; use scalar subfield '${suggestion.suggestedFieldPath}' for builder charts`
+          ),
+          {
+            details: withFlowSurfaceChartRepairDetails({
+              fieldPath,
+              dataSourceKey,
+              collectionName,
+              ...suggestion
+            })
+          }
         );
       }
     }
@@ -11805,7 +12216,12 @@ class FlowSurfacesService {
     }
     if (!((_c = sqlPreview.queryOutputs) == null ? void 0 : _c.length)) {
       (0, import_errors.throwBadRequest)(
-        "chart visual.mode='basic' requires previewable SQL query outputs; write query first, then read flowSurfaces:context(path='chart'), or use visual.mode='custom' after browser verification"
+        withChartRepairMessage(
+          "chart visual.mode='basic' requires previewable SQL query outputs; write query first, then read flowSurfaces:context(path='chart'), or use visual.mode='custom' after browser verification"
+        ),
+        {
+          details: withFlowSurfaceChartRepairDetails()
+        }
       );
     }
     const supportedOutputs = new Set(
@@ -11814,7 +12230,14 @@ class FlowSurfacesService {
     for (const mappingField of (0, import_chart_config.getChartVisualMappingAliases)(state.visual)) {
       if (!supportedOutputs.has(mappingField)) {
         (0, import_errors.throwBadRequest)(
-          `chart visual mappings only support SQL query output fields: ${Array.from(supportedOutputs).join(", ")}`
+          withChartRepairMessage(
+            `chart visual mappings only support SQL query output fields: ${Array.from(supportedOutputs).join(", ")}`
+          ),
+          {
+            details: withFlowSurfaceChartRepairDetails({
+              supportedOutputs: Array.from(supportedOutputs)
+            })
+          }
         );
       }
     }
@@ -11826,16 +12249,16 @@ class FlowSurfacesService {
     const normalized = (typeof sql === "string" ? sql : "").trim();
     const inspected = this.stripChartSqlForInspection(normalized).replace(/;+\s*$/, "").trim();
     if (!inspected) {
-      (0, import_errors.throwBadRequest)("chart query.sql cannot be empty");
+      throwChartRepairBadRequest("chart query.sql cannot be empty");
     }
     if (inspected.includes(";")) {
-      (0, import_errors.throwBadRequest)("chart query.sql must be a single read-only SELECT statement");
+      throwChartRepairBadRequest("chart query.sql must be a single read-only SELECT statement");
     }
     if (!/^(with|select)\b/i.test(inspected)) {
-      (0, import_errors.throwBadRequest)("chart query.sql must start with SELECT or WITH");
+      throwChartRepairBadRequest("chart query.sql must start with SELECT or WITH");
     }
     if (/\b(insert|update|delete|drop|alter|truncate|create|replace|grant|revoke|merge|call|execute)\b/i.test(inspected)) {
-      (0, import_errors.throwBadRequest)("chart query.sql must be read-only");
+      throwChartRepairBadRequest("chart query.sql must be read-only");
     }
     return normalized.replace(/;+\s*$/, "").trim();
   }
@@ -11853,7 +12276,7 @@ class FlowSurfacesService {
     if ((_a = db == null ? void 0 : db.sequelize) == null ? void 0 : _a.query) {
       return db.sequelize.query(sql, { bind, transaction });
     }
-    (0, import_errors.throwBadRequest)("chart SQL preview is unavailable for the target data source");
+    throwChartRepairBadRequest("chart SQL preview is unavailable for the target data source");
   }
   extractSqlChartPreviewAliases(metadata) {
     const pickName = (field) => {
@@ -11891,7 +12314,13 @@ class FlowSurfacesService {
   async resolveSqlChartPreview(query, _transaction) {
     var _a, _b;
     const normalizedSql = this.normalizeReadOnlyChartSql(query == null ? void 0 : query.sql);
-    const transformed = await (0, import_utils.transformSQL)(normalizedSql);
+    let transformed;
+    try {
+      transformed = await (0, import_utils.transformSQL)(normalizedSql);
+    } catch (error) {
+      const message = (error == null ? void 0 : error.message) || String(error);
+      throwChartRepairBadRequest(`chart query.sql is invalid: ${message}`);
+    }
     const riskyHints = [];
     const hasRuntimeContext = Object.keys((transformed == null ? void 0 : transformed.bind) || {}).length > 0 || Object.keys((transformed == null ? void 0 : transformed.liquidContext) || {}).length > 0;
     if (hasRuntimeContext) {
@@ -11947,7 +12376,7 @@ class FlowSurfacesService {
       }
       const outputAliases = Object.keys(firstRow);
       if (!outputAliases.length) {
-        (0, import_errors.throwBadRequest)("chart query.sql must expose at least one output column");
+        throwChartRepairBadRequest("chart query.sql must expose at least one output column");
       }
       return {
         queryOutputs: outputAliases.map((alias) => ({
@@ -11958,8 +12387,11 @@ class FlowSurfacesService {
         riskyHints
       };
     } catch (error) {
+      if (isFlowSurfaceChartRepairError(error)) {
+        throw error;
+      }
       const message = (error == null ? void 0 : error.message) || String(error);
-      (0, import_errors.throwBadRequest)(`chart query.sql is invalid: ${message}`);
+      throwChartRepairBadRequest(`chart query.sql is invalid: ${message}`);
     }
   }
   syncChartCardRuntimeStepParamsForUpdateSettings(current, nextPayload, replacementCardSettings) {
@@ -13967,6 +14399,97 @@ class FlowSurfacesService {
       }
     }
   }
+  hasActionWithPublicType(actions, type) {
+    return actions.some((action) => import_catalog.ACTION_KEY_BY_USE.get(String((action == null ? void 0 : action.use) || "").trim()) === type);
+  }
+  async ensureTableDefaultActionIntegrity(tableUid, options = {}) {
+    var _a, _b, _c, _d;
+    let table = await this.repository.findModelById(tableUid, {
+      transaction: options.transaction,
+      includeAsyncNode: true
+    });
+    if ((table == null ? void 0 : table.use) !== "TableBlockModel" || this.resolveTreeTableCreationContext(table)) {
+      return;
+    }
+    const descriptors = (0, import_default_block_actions.getFlowSurfaceDefaultBlockActions)({ blockType: "table" });
+    const blockActionDescriptors = descriptors.filter((descriptor) => descriptor.scope === "actions");
+    const recordActionDescriptors = descriptors.filter((descriptor) => descriptor.scope === "recordActions");
+    let blockActions = import_lodash.default.castArray(((_a = table == null ? void 0 : table.subModels) == null ? void 0 : _a.actions) || []);
+    for (const descriptor of blockActionDescriptors) {
+      if (this.hasActionWithPublicType(blockActions, descriptor.type)) {
+        continue;
+      }
+      await this.addAction(
+        {
+          target: { uid: tableUid },
+          type: descriptor.type,
+          ...descriptor.popup ? { popup: import_lodash.default.cloneDeep(descriptor.popup) } : {}
+        },
+        options
+      );
+      table = await this.repository.findModelById(tableUid, {
+        transaction: options.transaction,
+        includeAsyncNode: true
+      });
+      blockActions = import_lodash.default.castArray(((_b = table == null ? void 0 : table.subModels) == null ? void 0 : _b.actions) || []);
+    }
+    const actionsColumnUid = await this.ensureTableActionsColumn(tableUid, options.transaction);
+    let actionsColumn = await this.repository.findModelById(actionsColumnUid, {
+      transaction: options.transaction,
+      includeAsyncNode: true
+    });
+    let recordActions = import_lodash.default.castArray(((_c = actionsColumn == null ? void 0 : actionsColumn.subModels) == null ? void 0 : _c.actions) || []);
+    for (const descriptor of recordActionDescriptors) {
+      if (this.hasActionWithPublicType(recordActions, descriptor.type)) {
+        continue;
+      }
+      await this.addRecordAction(
+        {
+          target: { uid: tableUid },
+          type: descriptor.type,
+          ...descriptor.popup ? { popup: import_lodash.default.cloneDeep(descriptor.popup) } : {}
+        },
+        options
+      );
+      actionsColumn = await this.repository.findModelById(actionsColumnUid, {
+        transaction: options.transaction,
+        includeAsyncNode: true
+      });
+      recordActions = import_lodash.default.castArray(((_d = actionsColumn == null ? void 0 : actionsColumn.subModels) == null ? void 0 : _d.actions) || []);
+    }
+    const missingRecordActions = recordActionDescriptors.map((descriptor) => descriptor.type).filter((type) => !this.hasActionWithPublicType(recordActions, type));
+    if (missingRecordActions.length) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces table '${tableUid}' is missing required default record actions`, {
+        ruleId: "table-record-actions-required",
+        details: {
+          tableUid,
+          missingRecordActions,
+          repairHint: "Put row actions under recordActions, or omit/pass an empty recordActions array so Flow Surfaces can create the default View/Edit/Delete row actions."
+        }
+      });
+    }
+  }
+  collectNodeTreeDescendants(node, predicate, bucket = []) {
+    if (!node || typeof node !== "object") {
+      return bucket;
+    }
+    if (predicate(node)) {
+      bucket.push(node);
+    }
+    Object.values(import_lodash.default.isPlainObject(node.subModels) ? node.subModels : {}).forEach((subModel) => {
+      import_lodash.default.castArray(subModel).forEach((child) => this.collectNodeTreeDescendants(child, predicate, bucket));
+    });
+    return bucket;
+  }
+  async ensureSurfaceTableDefaultActionIntegrity(pageLocator, options = {}) {
+    const surface = await this.get(pageLocator, options);
+    const tables = this.collectNodeTreeDescendants(surface == null ? void 0 : surface.tree, (item) => (item == null ? void 0 : item.use) === "TableBlockModel");
+    for (const table of tables) {
+      if (table == null ? void 0 : table.uid) {
+        await this.ensureTableDefaultActionIntegrity(table.uid, options);
+      }
+    }
+  }
   async resolveReusableSingletonAction(input) {
     var _a, _b, _c;
     if (AUTO_SUBMIT_FORM_BLOCK_USES.has(input.ownerUse || "") && input.actionUse === "FormSubmitActionModel") {
@@ -14130,8 +14653,10 @@ class FlowSurfacesService {
     if (blockCatalogItem) {
       this.validateComposeActionGroups(blockCatalogItem.use, actions, recordActions, enabledPackages);
     }
-    const actionKeys = new Set(actions.map((item) => item.key).filter(Boolean));
-    const recordActionKeys = new Set(recordActions.map((item) => item.key).filter(Boolean));
+    const actionKeys = new Set(actions.map((item) => String(item.key || "").trim()).filter(Boolean));
+    const recordActionKeys = new Set(
+      recordActions.map((item) => String(item.key || "").trim()).filter(Boolean)
+    );
     const blockDescriptor = this.describeComposeBlock({
       index: index + 1,
       key,
@@ -14562,6 +15087,7 @@ class FlowSurfacesService {
           ...(0, import_service_utils.hasDefinedValue)(changes, [
             "pageSize",
             "density",
+            "enableRowSelection",
             "showRowNumbers",
             "sorting",
             "dataScope",
@@ -14575,6 +15101,7 @@ class FlowSurfacesService {
               ...(0, import_service_utils.hasOwnDefined)(changes, "pageSize") ? { pageSize: { pageSize: changes.pageSize } } : {},
               ...(0, import_service_utils.hasOwnDefined)(changes, "density") ? { tableDensity: { size: changes.density } } : {},
               ...(0, import_service_utils.hasOwnDefined)(changes, "quickEdit") ? { quickEdit: { editable: changes.quickEdit } } : {},
+              ...(0, import_service_utils.hasOwnDefined)(changes, "enableRowSelection") ? { enableRowSelection: { enableRowSelection: changes.enableRowSelection } } : {},
               ...(0, import_service_utils.hasOwnDefined)(changes, "showRowNumbers") ? { showRowNumbers: { showIndex: changes.showRowNumbers } } : {},
               ...(0, import_service_utils.hasOwnDefined)(changes, "sorting") ? {
                 defaultSorting: {
@@ -15952,6 +16479,7 @@ class FlowSurfacesService {
     );
   }
   async configureJSColumn(target, changes, options) {
+    assertNoJsDeclarativeOpenView("jsColumn", changes, "JSColumnModel");
     const allowedKeys = (0, import_configure_options.getConfigureOptionKeysForUse)("JSColumnModel");
     (0, import_service_utils.assertSupportedSimpleChanges)("jsColumn", changes, allowedKeys);
     return this.updateSettings(
@@ -15985,6 +16513,8 @@ class FlowSurfacesService {
     );
   }
   async configureJSItem(target, changes, options) {
+    const { currentUse = "JSItemModel", ...updateOptions } = options;
+    assertNoJsDeclarativeOpenView("jsItem", changes, currentUse);
     const allowedKeys = (0, import_configure_options.getConfigureOptionKeysForUse)("JSItemModel");
     (0, import_service_utils.assertSupportedSimpleChanges)("jsItem", changes, allowedKeys);
     return this.updateSettings(
@@ -16009,7 +16539,7 @@ class FlowSurfacesService {
           }
         } : void 0
       },
-      options
+      updateOptions
     );
   }
   async configureDividerItem(target, changes, options) {
@@ -16060,6 +16590,7 @@ class FlowSurfacesService {
       transaction: options.transaction,
       includeAsyncNode: true
     }) : null;
+    assertNoJsDeclarativeOpenView("field", changes, innerField == null ? void 0 : innerField.use);
     const currentFieldInit = ((_e = (_d = current == null ? void 0 : current.stepParams) == null ? void 0 : _d.fieldSettings) == null ? void 0 : _e.init) || ((_g = (_f = innerField == null ? void 0 : innerField.stepParams) == null ? void 0 : _f.fieldSettings) == null ? void 0 : _g.init) || {};
     const bindingChange = (0, import_service_utils.hasDefinedValue)(wrapperChanges, ["fieldPath", "associationPathName"]);
     const normalizedBinding = bindingChange ? this.normalizeDisplayFieldBinding({
@@ -16271,6 +16802,8 @@ class FlowSurfacesService {
     const enabledPackages = await this.resolveEnabledPluginPackages(options);
     const resolved = await this.locator.resolve(target, options);
     const current = await this.loadResolvedNode(resolved, options.transaction);
+    const isJsFieldNode = ["JSFieldModel", "JSEditableFieldModel"].includes((current == null ? void 0 : current.use) || "");
+    assertNoJsDeclarativeOpenView("field", changes, current == null ? void 0 : current.use);
     (0, import_service_utils.assertSupportedSimpleChanges)(
       "field",
       changes,
@@ -16281,7 +16814,6 @@ class FlowSurfacesService {
       transaction: options.transaction,
       includeAsyncNode: true
     }) : null;
-    const isJsFieldNode = ["JSFieldModel", "JSEditableFieldModel"].includes((current == null ? void 0 : current.use) || "");
     if ((0, import_service_utils.hasDefinedValue)(changes, ["code", "version"]) && !isJsFieldNode) {
       (0, import_errors.throwBadRequest)(`flowSurfaces configure field '${current == null ? void 0 : current.use}' does not support code/version`);
     }
@@ -16486,6 +17018,93 @@ class FlowSurfacesService {
   isAIEmployeeActionUse(use) {
     return String(use || "").trim() === AI_EMPLOYEE_ACTION_USE;
   }
+  stableSerializeAIEmployeeValue(value) {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => this.stableSerializeAIEmployeeValue(item)).join(",")}]`;
+    }
+    if (import_lodash.default.isPlainObject(value)) {
+      return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${this.stableSerializeAIEmployeeValue(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+  }
+  buildAIEmployeeActionDedupIdentity(values) {
+    var _a, _b, _c, _d, _e, _f;
+    const username = String(((_b = (_a = values == null ? void 0 : values.props) == null ? void 0 : _a.aiEmployee) == null ? void 0 : _b.username) || "").trim();
+    if (!username) {
+      return "";
+    }
+    return this.stableSerializeAIEmployeeValue({
+      username,
+      auto: typeof ((_c = values == null ? void 0 : values.props) == null ? void 0 : _c.auto) === "boolean" ? values.props.auto : false,
+      workContext: this.normalizeAIEmployeeWorkContextForDedupIdentity((_e = (_d = values == null ? void 0 : values.props) == null ? void 0 : _d.context) == null ? void 0 : _e.workContext),
+      tasks: this.normalizeAIEmployeeTasksForDedupIdentity(
+        import_lodash.default.get(values, ["stepParams", ...AI_EMPLOYEE_TASK_STEP_PARAMS_PATH])
+      ),
+      style: {
+        ...AI_EMPLOYEE_DEFAULT_STYLE,
+        ...import_lodash.default.isPlainObject((_f = values == null ? void 0 : values.props) == null ? void 0 : _f.style) ? import_lodash.default.pick(values.props.style, AI_EMPLOYEE_STYLE_PUBLIC_KEYS) : {}
+      }
+    });
+  }
+  normalizeAIEmployeeWorkContextForDedupIdentity(value) {
+    return import_lodash.default.castArray(value || []).map(
+      (item) => import_lodash.default.isPlainObject(item) ? import_lodash.default.pick(item, AI_EMPLOYEE_WORK_CONTEXT_PUBLIC_KEYS) : item
+    );
+  }
+  normalizeAIEmployeeTasksForDedupIdentity(value) {
+    return import_lodash.default.castArray(value || []).map((task) => {
+      if (!import_lodash.default.isPlainObject(task)) {
+        return task;
+      }
+      const output = import_lodash.default.pick(task, AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS);
+      if (import_lodash.default.isPlainObject(output.message)) {
+        output.message = import_lodash.default.pick(output.message, AI_EMPLOYEE_TASK_MESSAGE_PUBLIC_KEYS);
+        if (Object.prototype.hasOwnProperty.call(output.message, "workContext")) {
+          output.message.workContext = this.normalizeAIEmployeeWorkContextForDedupIdentity(output.message.workContext);
+        }
+      }
+      if (import_lodash.default.isPlainObject(output.model)) {
+        output.model = import_lodash.default.pick(output.model, AI_EMPLOYEE_TASK_MODEL_PUBLIC_KEYS);
+      }
+      if (import_lodash.default.isPlainObject(output.skillSettings)) {
+        output.skillSettings = import_lodash.default.pick(output.skillSettings, AI_EMPLOYEE_SKILL_SETTINGS_PUBLIC_KEYS);
+      }
+      return output;
+    });
+  }
+  async assertNoDuplicateAIEmployeeAction(actionName, parentUid, values, transaction) {
+    var _a;
+    const identity = this.buildAIEmployeeActionDedupIdentity(values);
+    if (!identity) {
+      return;
+    }
+    const parentNode = await this.repository.findModelById(parentUid, {
+      transaction,
+      includeAsyncNode: true
+    });
+    const duplicate = import_lodash.default.castArray(((_a = parentNode == null ? void 0 : parentNode.subModels) == null ? void 0 : _a.actions) || []).find((action) => {
+      if (!this.isAIEmployeeActionUse(action == null ? void 0 : action.use)) {
+        return false;
+      }
+      return this.buildAIEmployeeActionDedupIdentity({
+        props: action.props,
+        stepParams: action.stepParams
+      }) === identity;
+    });
+    if (!(duplicate == null ? void 0 : duplicate.uid)) {
+      return;
+    }
+    (0, import_errors.throwBadRequest)(
+      `flowSurfaces ${actionName} duplicates an existing AI employee action in the same action container; reuse or update the existing button instead of appending another identical AI employee action`,
+      {
+        ruleId: "duplicate-ai-employee-action",
+        details: {
+          existingUid: duplicate.uid,
+          repairHint: "Remove the duplicate aiEmployee action, or change username, task title/key, or workContext if this is a genuinely different AI employee action."
+        }
+      }
+    );
+  }
   hasAIEmployeePublicSettings(settings) {
     return import_lodash.default.isPlainObject(settings) && AI_EMPLOYEE_PUBLIC_SETTING_KEYS.some((key) => Object.prototype.hasOwnProperty.call(settings, key));
   }
@@ -16493,16 +17112,31 @@ class FlowSurfacesService {
     const unsupportedKeys = Object.keys(settings || {}).filter((key) => !AI_EMPLOYEE_PUBLIC_SETTING_KEYS.includes(key));
     if (unsupportedKeys.length) {
       (0, import_errors.throwBadRequest)(
-        `flowSurfaces ${actionName} AI employee settings do not support keys: ${unsupportedKeys.join(", ")}`
+        `flowSurfaces ${actionName} AI employee settings do not support keys: ${unsupportedKeys.join(
+          ", "
+        )}; allowed keys: ${AI_EMPLOYEE_PUBLIC_SETTING_KEYS.join(
+          ", "
+        )}; repairHint: use top-level username, auto, workContext, tasks, or style instead of raw props/stepParams`
       );
     }
   }
+  aiEmployeeNestedRepairHint(path) {
+    if (path.includes("workContext")) {
+      return AI_EMPLOYEE_WORK_CONTEXT_REPAIR_HINT;
+    }
+    if (path.includes("tasks")) {
+      return AI_EMPLOYEE_TASK_REPAIR_HINT;
+    }
+    return "Use only the documented public AI employee settings keys for this nested object.";
+  }
   assertOnlyAIEmployeeNestedPublicSettings(actionName, path, value, allowedKeys) {
     const unsupportedKeys = Object.keys(value || {}).filter((key) => !allowedKeys.includes(key));
     if (!unsupportedKeys.length) {
       return;
     }
-    (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${path} does not support key '${unsupportedKeys[0]}'`);
+    (0, import_errors.throwBadRequest)(
+      `flowSurfaces ${actionName} ${path} does not support key '${unsupportedKeys[0]}'; allowed keys: ${allowedKeys.join(", ")}; repairHint: ${this.aiEmployeeNestedRepairHint(path)}`
+    );
   }
   assertNoAIEmployeeInternalPropSettings(actionName, values) {
     const props = values == null ? void 0 : values.props;
@@ -16665,8 +17299,13 @@ class FlowSurfacesService {
     return username;
   }
   assertAIEmployeeWorkContextType(actionName, itemPath, item) {
+    if (!Object.prototype.hasOwnProperty.call(item, "type") || import_lodash.default.isUndefined(item.type) || item.type === null) {
+      return;
+    }
     if (String(item.type || "").trim() !== "flow-model") {
-      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${itemPath}.type must be 'flow-model'`);
+      (0, import_errors.throwBadRequest)(
+        `flowSurfaces ${actionName} ${itemPath}.type only supports 'flow-model'; omit type to use the default flow-model context. repairHint: ${AI_EMPLOYEE_WORK_CONTEXT_REPAIR_HINT}`
+      );
     }
   }
   normalizeAIEmployeeWorkContext(actionName, value, options) {
@@ -17099,9 +17738,18 @@ ${AI_EMPLOYEE_CURRENT_RECORD_PROMPT_VARIABLE}` : AI_EMPLOYEE_CURRENT_RECORD_PROM
       (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${options.path} must be an object`);
     }
     const next = import_lodash.default.pick(import_lodash.default.isPlainObject(existing) ? import_lodash.default.cloneDeep(existing) : {}, AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS);
+    if (Object.prototype.hasOwnProperty.call(patch, "prompt") && import_lodash.default.isPlainObject(patch.message) && Object.prototype.hasOwnProperty.call(patch.message, "user")) {
+      (0, import_errors.throwBadRequest)(
+        `flowSurfaces ${actionName} ${options.path} cannot set both prompt and message.user; prompt is an alias for message.user. repairHint: keep only one of ${options.path}.prompt or ${options.path}.message.user`
+      );
+    }
     Object.entries(patch).forEach(([key, value]) => {
-      if (!AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS.includes(key)) {
-        (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${options.path} does not support key '${key}'`);
+      if (!AI_EMPLOYEE_TASK_PATCH_PUBLIC_SETTING_KEYS.includes(key)) {
+        (0, import_errors.throwBadRequest)(
+          `flowSurfaces ${actionName} ${options.path} does not support key '${key}'; allowed keys: ${AI_EMPLOYEE_TASK_PATCH_PUBLIC_SETTING_KEYS.join(
+            ", "
+          )}; repairHint: ${AI_EMPLOYEE_TASK_REPAIR_HINT}`
+        );
       }
       if (key === "message") {
         next.message = this.normalizeAIEmployeeTaskMessage(actionName, `${options.path}.message`, value, next.message, {
@@ -17110,6 +17758,18 @@ ${AI_EMPLOYEE_CURRENT_RECORD_PROMPT_VARIABLE}` : AI_EMPLOYEE_CURRENT_RECORD_PROM
         });
         return;
       }
+      if (key === "prompt") {
+        if (typeof value !== "string") {
+          (0, import_errors.throwBadRequest)(
+            `flowSurfaces ${actionName} ${options.path}.prompt must be a string; repairHint: ${AI_EMPLOYEE_TASK_REPAIR_HINT}`
+          );
+        }
+        next.message = {
+          ...import_lodash.default.isPlainObject(next.message) ? import_lodash.default.cloneDeep(next.message) : {},
+          user: value
+        };
+        return;
+      }
       if (key === "title") {
         if (typeof value !== "string") {
           (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} ${options.path}.title must be a string`);
@@ -17324,6 +17984,9 @@ ${AI_EMPLOYEE_CURRENT_RECORD_PROMPT_VARIABLE}` : AI_EMPLOYEE_CURRENT_RECORD_PROM
     }) : null);
     changes = await this.normalizeActionPanelActionChanges(changes, options);
     const allowedKeys = (0, import_configure_options.getConfigureOptionKeysForUse)(use);
+    if ((0, import_service_utils.hasOwnDefined)(changes, "openView") && !allowedKeys.includes("openView") && JS_POPUP_GUIDANCE_USES.has(use)) {
+      (0, import_errors.throwBadRequest)(withJsPopupGuidance(`flowSurfaces configure action '${use}' does not support openView`, use));
+    }
     (0, import_service_utils.assertSupportedSimpleChanges)("action", changes, allowedKeys);
     if (this.isAIEmployeeActionUse(use)) {
       const aiEmployeeSettingsPayload = await this.normalizeAIEmployeeActionPublicSettings(
@@ -17417,7 +18080,7 @@ ${AI_EMPLOYEE_CURRENT_RECORD_PROMPT_VARIABLE}` : AI_EMPLOYEE_CURRENT_RECORD_PROM
           openView: import_lodash.default.cloneDeep(changes.openView)
         };
       } else if (!POPUP_ACTION_USES.has(use)) {
-        (0, import_errors.throwBadRequest)(`flowSurfaces configure action '${use}' does not support openView`);
+        (0, import_errors.throwBadRequest)(withJsPopupGuidance(`flowSurfaces configure action '${use}' does not support openView`, use));
       } else {
         let openView = import_lodash.default.cloneDeep(changes.openView);
         if (use === "AddChildActionModel") {