@nocobase/plugin-flow-engine 2.2.0-beta.1 → 2.2.0-beta.10

package/dist/server/flow-surfaces/filter-group.js

@@ -36,11 +36,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var filter_group_exports = {};
 __export(filter_group_exports, {
+  FLOW_SURFACE_DATE_FILTER_OPERATORS: () => FLOW_SURFACE_DATE_FILTER_OPERATORS,
   FLOW_SURFACE_EMPTY_FILTER_GROUP: () => FLOW_SURFACE_EMPTY_FILTER_GROUP,
   FLOW_SURFACE_FILTER_GROUP_EXAMPLE: () => FLOW_SURFACE_FILTER_GROUP_EXAMPLE,
   assertFlowSurfaceFilterGroupShape: () => assertFlowSurfaceFilterGroupShape,
   assertFlowSurfaceFilterOperator: () => assertFlowSurfaceFilterOperator,
+  isFlowSurfaceDateLikeFieldMeta: () => isFlowSurfaceDateLikeFieldMeta,
   normalizeFlowSurfaceCompatibleFilterGroupValue: () => normalizeFlowSurfaceCompatibleFilterGroupValue,
+  normalizeFlowSurfaceDateConditionValue: () => normalizeFlowSurfaceDateConditionValue,
   normalizeFlowSurfaceFilterDateValue: () => normalizeFlowSurfaceFilterDateValue,
   normalizeFlowSurfaceFilterGroupValue: () => normalizeFlowSurfaceFilterGroupValue,
   normalizeFlowSurfaceStrictFilterDateValue: () => normalizeFlowSurfaceStrictFilterDateValue
@@ -76,6 +79,17 @@ const FLOW_SURFACE_DATE_FILTER_OPERATORS = /* @__PURE__ */ new Set([
   "$dateNotAfter",
   "$dateBetween"
 ]);
+const FLOW_SURFACE_DATE_COMPARISON_OPERATORS = /* @__PURE__ */ new Set(["$eq", "$ne", "$lt", "$lte", "$gt", "$gte", "$in", "$notIn"]);
+const FLOW_SURFACE_EMPTY_FILTER_OPERATORS = /* @__PURE__ */ new Set(["$empty", "$notEmpty", "$exists", "$notExists"]);
+const FLOW_SURFACE_DATE_LIKE_TYPES = /* @__PURE__ */ new Set([
+  "date",
+  "datetime",
+  "dateonly",
+  "datetimenotz",
+  "unixtimestamp",
+  "createdat",
+  "updatedat"
+]);
 const FLOW_SURFACE_DATE_RANGE_TYPES = /* @__PURE__ */ new Set([
   "today",
   "yesterday",
@@ -109,6 +123,18 @@ const FLOW_SURFACE_DATE_VALUE_REPAIR_EXAMPLE = {
     }
   ]
 };
+const FLOW_SURFACE_DATE_CONDITION_REPAIR_HINT = "Date/DateTime condition values must be valid UI date values or safe context-path templates. Do not use template arithmetic such as {{$now - 14 * 24 * 60 * 60 * 1000}}; use date operators such as $dateBefore with a relative descriptor instead.";
+const FLOW_SURFACE_DATE_CONDITION_REPAIR_EXAMPLE = {
+  logic: "$and",
+  items: [
+    {
+      path: "lastFollowUpAt",
+      operator: "$dateBefore",
+      value: { type: "past", number: 14, unit: "day" }
+    }
+  ]
+};
+const FLOW_SURFACE_ISO_DATE_VALUE_RE = /^\d{4}-\d{2}-\d{2}(?:[T\s]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
 const FLOW_SURFACE_KNOWN_FILTER_OPERATORS = buildFlowSurfaceKnownFilterOperators();
 function buildFlowSurfaceKnownFilterOperators() {
   const operators = new Set(Object.keys(import_database.operators));
@@ -156,13 +182,16 @@ function assertFlowSurfaceFilterOperator(operator, path) {
     );
   }
 }
-function normalizeFlowSurfaceFilterDateValue(operator, value, path) {
+function normalizeFlowSurfaceFilterDateValue(operator, value, path, options = {}) {
   if (typeof operator !== "string" || !FLOW_SURFACE_DATE_FILTER_OPERATORS.has(operator)) {
     return value;
   }
+  if (options.allowContextPathValue && isFlowSurfaceContextPathValueObject(value)) {
+    return value;
+  }
   return normalizeFlowSurfaceDateValue(value, path);
 }
-function normalizeFlowSurfaceStrictFilterDateValue(operator, value, path) {
+function normalizeFlowSurfaceStrictFilterDateValue(operator, value, path, options = {}) {
   if (typeof operator !== "string" || !FLOW_SURFACE_DATE_FILTER_OPERATORS.has(operator)) {
     return value;
   }
@@ -171,8 +200,33 @@ function normalizeFlowSurfaceStrictFilterDateValue(operator, value, path) {
       invalidReason: "date filter value is required"
     });
   }
+  if (options.allowContextPathValue && isFlowSurfaceContextPathValueObject(value)) {
+    return value;
+  }
   return normalizeFlowSurfaceDateValue(value, path);
 }
+function isFlowSurfaceDateLikeFieldMeta(value) {
+  const fieldType = String((value == null ? void 0 : value.type) || "").trim().toLowerCase();
+  const fieldInterface = String((value == null ? void 0 : value.interface) || "").trim().toLowerCase();
+  return FLOW_SURFACE_DATE_LIKE_TYPES.has(fieldType) || FLOW_SURFACE_DATE_LIKE_TYPES.has(fieldInterface);
+}
+function normalizeFlowSurfaceDateConditionValue(operator, value, path, options = {}) {
+  const normalizedOperator = typeof operator === "string" ? operator.trim() : "";
+  if (!normalizedOperator || FLOW_SURFACE_EMPTY_FILTER_OPERATORS.has(normalizedOperator)) {
+    return value;
+  }
+  if (options.allowContextPathValue && isFlowSurfaceContextPathValueObject(value)) {
+    return value;
+  }
+  if (FLOW_SURFACE_DATE_FILTER_OPERATORS.has(normalizedOperator)) {
+    assertNoUnsafeFlowSurfaceDateTemplateValues(value, path, options);
+    return normalizeFlowSurfaceStrictFilterDateValue(normalizedOperator, value, path);
+  }
+  if (!FLOW_SURFACE_DATE_COMPARISON_OPERATORS.has(normalizedOperator)) {
+    return value;
+  }
+  return normalizeFlowSurfaceDateComparisonValue(normalizedOperator, value, path, options);
+}
 function normalizeFlowSurfaceFilterGroupValue(value, errorPrefix, options = {}) {
   const normalized = value === null || import_lodash.default.isPlainObject(value) && !Object.keys(value).length ? import_lodash.default.cloneDeep(FLOW_SURFACE_EMPTY_FILTER_GROUP) : import_lodash.default.cloneDeep(value);
   try {
@@ -332,7 +386,11 @@ function normalizeFlowSurfaceFilterGroupDateValues(filter, errorPrefix, options)
       normalizeFlowSurfaceFilterGroupDateValues(item, itemPath, options);
       return;
     }
-    item.value = options.strictDateValues ? normalizeFlowSurfaceStrictFilterDateValue(item.operator, item.value, `${itemPath}.value`) : normalizeFlowSurfaceFilterDateValue(item.operator, item.value, `${itemPath}.value`);
+    item.value = options.strictDateValues ? normalizeFlowSurfaceStrictFilterDateValue(item.operator, item.value, `${itemPath}.value`, {
+      allowContextPathValue: options.allowContextPathValue
+    }) : normalizeFlowSurfaceFilterDateValue(item.operator, item.value, `${itemPath}.value`, {
+      allowContextPathValue: options.allowContextPathValue
+    });
   });
 }
 function normalizeFlowSurfaceDateValue(value, path) {
@@ -344,6 +402,82 @@ function normalizeFlowSurfaceDateValue(value, path) {
   }
   return normalizeFlowSurfaceDateValuePart(value, path);
 }
+function normalizeFlowSurfaceDateComparisonValue(operator, value, path, options) {
+  if (operator === "$in" || operator === "$notIn") {
+    if (!Array.isArray(value)) {
+      throwInvalidFlowSurfaceDateConditionValue(path, value, {
+        ...options,
+        operator,
+        invalidReason: "date comparison array operators require an array value"
+      });
+    }
+    return value.map(
+      (item, index) => normalizeFlowSurfaceDateComparisonValuePart(item, `${path}[${index}]`, {
+        ...options,
+        operator
+      })
+    );
+  }
+  return normalizeFlowSurfaceDateComparisonValuePart(value, path, {
+    ...options,
+    operator
+  });
+}
+function normalizeFlowSurfaceDateComparisonValuePart(value, path, options) {
+  if (import_lodash.default.isNil(value) || value === "") {
+    throwInvalidFlowSurfaceDateConditionValue(path, value, {
+      ...options,
+      invalidReason: "date comparison value is required; use $empty or $notEmpty for empty checks"
+    });
+  }
+  if (options.allowContextPathValue && isFlowSurfaceContextPathValueObject(value)) {
+    return value;
+  }
+  if (isTemplateDateString(value)) {
+    if (isUnsafeFlowSurfaceDateTemplateString(value)) {
+      throwInvalidFlowSurfaceDateConditionValue(path, value, {
+        ...options,
+        invalidReason: "date condition template strings must be simple context-path references; template arithmetic, $now, Date/dayjs/moment calls, and Invalid date are not supported"
+      });
+    }
+    return value;
+  }
+  if (import_lodash.default.isDate(value)) {
+    if (!Number.isNaN(value.getTime())) {
+      return value;
+    }
+    throwInvalidFlowSurfaceDateConditionValue(path, value, {
+      ...options,
+      invalidReason: "date condition value must be a valid Date"
+    });
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim();
+    if (/invalid\s+date/i.test(normalized)) {
+      throwInvalidFlowSurfaceDateConditionValue(path, value, {
+        ...options,
+        invalidReason: "date condition value cannot be Invalid date"
+      });
+    }
+    if (isFlowSurfaceIsoLikeDateValue(normalized)) {
+      return normalized;
+    }
+    throwInvalidFlowSurfaceDateConditionValue(path, value, {
+      ...options,
+      invalidReason: "date comparison strings must use concrete YYYY-MM-DD or ISO-like date/datetime strings"
+    });
+  }
+  if (import_lodash.default.isPlainObject(value)) {
+    throwInvalidFlowSurfaceDateConditionValue(path, value, {
+      ...options,
+      invalidReason: "relative date descriptors require date operators such as $dateBefore or $dateBetween instead of comparison operators"
+    });
+  }
+  throwInvalidFlowSurfaceDateConditionValue(path, value, {
+    ...options,
+    invalidReason: "date condition value must be an exact date string, ISO datetime string, or safe context path template"
+  });
+}
 function normalizeFlowSurfaceDateArrayValue(value, path) {
   if (value.length !== 2) {
     throwInvalidFlowSurfaceDateValue(path, value, {
@@ -386,6 +520,25 @@ function isFlowSurfaceExactDateValue(value) {
     return parsed.isValid() && parsed.format(format) === value;
   });
 }
+function isFlowSurfaceIsoLikeDateValue(value) {
+  const match = FLOW_SURFACE_ISO_DATE_VALUE_RE.exec(value);
+  if (!match) {
+    return false;
+  }
+  const [year, month, day] = value.slice(0, 10).split("-").map((item) => Number(item));
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return false;
+  }
+  const timeMatch = /[T\s](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,6}))?)?/.exec(value);
+  if (!timeMatch) {
+    return true;
+  }
+  const hour = Number(timeMatch[1]);
+  const minute = Number(timeMatch[2]);
+  const second = Number(timeMatch[3] || 0);
+  return hour <= 23 && minute <= 59 && second <= 59 && (0, import_utils.dayjs)(value).isValid();
+}
 function normalizeRelativeDateDescriptor(value, path) {
   const invalidKeys = Object.keys(value).filter((key) => !FLOW_SURFACE_RELATIVE_DATE_DESCRIPTOR_KEYS.has(key));
   if (invalidKeys.length) {
@@ -456,6 +609,67 @@ function normalizeRelativeDateDescriptor(value, path) {
 function isTemplateDateString(value) {
   return typeof value === "string" && /^\s*\{\{[\s\S]*\}\}\s*$/.test(value);
 }
+function isFlowSurfaceContextPathValueObject(value) {
+  if (!import_lodash.default.isPlainObject(value) || value.source !== "path") {
+    return false;
+  }
+  const path = value.path;
+  if (typeof path !== "string") {
+    return false;
+  }
+  const normalizedPath = path.trim();
+  if (isTemplateDateString(normalizedPath)) {
+    return !isUnsafeFlowSurfaceDateTemplateString(normalizedPath);
+  }
+  return isSimpleFlowSurfaceTemplateReference(normalizedPath);
+}
+function extractTemplateDateExpression(value) {
+  return value.replace(/^\s*\{\{\s*/, "").replace(/\s*\}\}\s*$/, "").trim();
+}
+function isSimpleFlowSurfaceTemplateReference(expression) {
+  const identifier = "[A-Za-z_$][A-Za-z0-9_$-]*";
+  const segment = `(?:\\.${identifier}|\\[(?:\\d+|"[^"\\]]+"|'[^'\\]]+')\\])`;
+  return new RegExp(`^${identifier}(?:${segment})*$`).test(expression.replace(/\s+/g, ""));
+}
+function isUnsafeFlowSurfaceDateTemplateString(value) {
+  const expression = extractTemplateDateExpression(value);
+  if (!expression) {
+    return true;
+  }
+  if (/\$now\b/i.test(expression)) {
+    return true;
+  }
+  if (/invalid\s+date/i.test(expression)) {
+    return true;
+  }
+  if (/\bnew\s+Date\b|\bDate\s*\(|\bdayjs\s*\(|\bmoment\s*\(/.test(expression)) {
+    return true;
+  }
+  if (isSimpleFlowSurfaceTemplateReference(expression)) {
+    return false;
+  }
+  return /[+\-*/%()]|=>/.test(expression);
+}
+function assertNoUnsafeFlowSurfaceDateTemplateValues(value, path, options = {}) {
+  if (isTemplateDateString(value)) {
+    if (isUnsafeFlowSurfaceDateTemplateString(value)) {
+      throwInvalidFlowSurfaceDateConditionValue(path, value, {
+        ...options,
+        invalidReason: "date filter template strings must be simple context-path references; template arithmetic, $now, Date/dayjs/moment calls, and Invalid date are not supported"
+      });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoUnsafeFlowSurfaceDateTemplateValues(item, `${path}[${index}]`, options));
+    return;
+  }
+  if (import_lodash.default.isPlainObject(value)) {
+    Object.entries(value).forEach(
+      ([key, item]) => assertNoUnsafeFlowSurfaceDateTemplateValues(item, `${path}.${key}`, options)
+    );
+  }
+}
 function hasTemplateDateValue(value) {
   if (isTemplateDateString(value)) {
     return true;
@@ -468,6 +682,18 @@ function hasTemplateDateValue(value) {
   }
   return false;
 }
+function throwInvalidFlowSurfaceDateConditionValue(path, value, details = {}) {
+  (0, import_errors.throwBadRequest)(`${path} must be a valid Date/DateTime condition value`, {
+    path,
+    ruleId: "date-condition-value-invalid",
+    details: {
+      invalidValue: value,
+      ...details,
+      repairHint: FLOW_SURFACE_DATE_CONDITION_REPAIR_HINT,
+      repairExample: FLOW_SURFACE_DATE_CONDITION_REPAIR_EXAMPLE
+    }
+  });
+}
 function throwInvalidFlowSurfaceDateValue(path, value, details = {}) {
   (0, import_errors.throwBadRequest)(`${path} must be a valid date filter value`, {
     path,
@@ -482,11 +708,14 @@ function throwInvalidFlowSurfaceDateValue(path, value, details = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FLOW_SURFACE_DATE_FILTER_OPERATORS,
   FLOW_SURFACE_EMPTY_FILTER_GROUP,
   FLOW_SURFACE_FILTER_GROUP_EXAMPLE,
   assertFlowSurfaceFilterGroupShape,
   assertFlowSurfaceFilterOperator,
+  isFlowSurfaceDateLikeFieldMeta,
   normalizeFlowSurfaceCompatibleFilterGroupValue,
+  normalizeFlowSurfaceDateConditionValue,
   normalizeFlowSurfaceFilterDateValue,
   normalizeFlowSurfaceFilterGroupValue,
   normalizeFlowSurfaceStrictFilterDateValue

package/dist/server/flow-surfaces/planning/compiler.d.ts

@@ -22,6 +22,7 @@ type CompilePlanStepDeps = NormalizePlanSelectorDeps & {
     resolveLocator: (target: FlowSurfaceReadLocator, options?: {
         transaction?: any;
     }) => Promise<FlowSurfaceResolvedTarget>;
+    loadResolvedSurfaceTree?: (resolved: FlowSurfaceResolvedTarget, transaction?: any) => Promise<any>;
     buildPlanKeyKind: (node: any, resolvedKind?: string) => string;
 };
 export declare function normalizePlanSelector(actionName: string, selector: any, deps: NormalizePlanSelectorDeps, fieldName?: string, options?: NormalizePlanSelectorOptions): FlowSurfacePlanSelector;

package/dist/server/flow-surfaces/planning/compiler.js

@@ -180,6 +180,8 @@ async function resolvePlanSelectorInContext(actionName, selector, context, deps,
     uid: resolved.uid,
     source: "system",
     kind: deps.buildPlanKeyKind(node, resolved.kind),
+    node: node || resolved.node,
+    resolved,
     locator: (0, import_service_utils.buildDefinedPayload)({
       uid: normalizedSelector.locator.uid,
       pageSchemaUid: normalizedSelector.locator.pageSchemaUid,
@@ -217,51 +219,146 @@ function buildSelectorRuntimeValue(selector) {
   }
   return selector.uid;
 }
+function getResolvedSelectorUid(selector) {
+  if (!selector || "summary" in selector) {
+    return void 0;
+  }
+  return selector.uid;
+}
+function isReplaceComposeStep(step) {
+  var _a;
+  return step.action === "compose" && String(((_a = step.values) == null ? void 0 : _a.mode) || "").trim() === "replace";
+}
+function assertReplaceComposeTargetSupportsScopeResolution(actionName, index, step, target) {
+  if (!isReplaceComposeStep(step) || !target || !("summary" in target) || target.summary.source !== "step") {
+    return;
+  }
+  (0, import_errors.throwBadRequest)(
+    `flowSurfaces ${actionName} plan.steps[${index}] compose replace does not support selectors.target.step; use a concrete locator or key for the existing replace target`
+  );
+}
+function collectDescendantUids(node, carry = /* @__PURE__ */ new Set()) {
+  if (!node || typeof node !== "object") {
+    return carry;
+  }
+  for (const value of Object.values(node.subModels || {})) {
+    for (const child of import_lodash.default.castArray(value)) {
+      if (child == null ? void 0 : child.uid) {
+        carry.add(child.uid);
+      }
+      collectDescendantUids(child, carry);
+    }
+  }
+  return carry;
+}
+function collectNodeAndDescendantUids(node, carry = /* @__PURE__ */ new Set()) {
+  if (!node || typeof node !== "object") {
+    return carry;
+  }
+  if (node.uid) {
+    carry.add(node.uid);
+  }
+  return collectDescendantUids(node, carry);
+}
+function findNodeInTreeByUid(node, uid) {
+  if (!node || typeof node !== "object" || !uid) {
+    return void 0;
+  }
+  if (node.uid === uid) {
+    return node;
+  }
+  for (const value of Object.values(node.subModels || {})) {
+    for (const child of import_lodash.default.castArray(value)) {
+      const matched = findNodeInTreeByUid(child, uid);
+      if (matched) {
+        return matched;
+      }
+    }
+  }
+  return void 0;
+}
+function getContextNodeByUid(context, uid) {
+  if (!uid) {
+    return void 0;
+  }
+  return findNodeInTreeByUid(context.publicTree, uid) || findNodeInTreeByUid(context.rawTree, uid);
+}
+function getSingleSubModel(node, key) {
+  var _a;
+  const value = (_a = node == null ? void 0 : node.subModels) == null ? void 0 : _a[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+function getSubModelList(node, key) {
+  var _a;
+  return import_lodash.default.castArray(((_a = node == null ? void 0 : node.subModels) == null ? void 0 : _a[key]) || []).filter((item) => item && typeof item === "object");
+}
+function isGridNode(node) {
+  return typeof (node == null ? void 0 : node.use) === "string" && node.use.endsWith("GridModel");
+}
+function resolveReplaceComposeGridNode(targetNode) {
+  if (!targetNode || typeof targetNode !== "object") {
+    return void 0;
+  }
+  if (isGridNode(targetNode)) {
+    return targetNode;
+  }
+  const directGrid = getSingleSubModel(targetNode, "grid");
+  if (directGrid) {
+    return directGrid;
+  }
+  const firstTab = getSubModelList(targetNode, "tabs")[0];
+  const firstTabGrid = getSingleSubModel(firstTab, "grid");
+  if (firstTabGrid) {
+    return firstTabGrid;
+  }
+  const popupPage = getSingleSubModel(targetNode, "page");
+  const firstPopupTab = getSubModelList(popupPage, "tabs")[0];
+  return getSingleSubModel(firstPopupTab, "grid");
+}
+async function collectReplaceScopeExistingKeys(step, context, target, deps, options = {}) {
+  if (!isReplaceComposeStep(step)) {
+    return /* @__PURE__ */ new Set();
+  }
+  let targetNode = getContextNodeByUid(context, getResolvedSelectorUid(target)) || (!target || "summary" in target ? void 0 : target.node);
+  if (!targetNode && target && !("summary" in target) && target.resolved && deps.loadResolvedSurfaceTree) {
+    targetNode = await deps.loadResolvedSurfaceTree(target.resolved, options.transaction);
+  }
+  if (!targetNode) {
+    return /* @__PURE__ */ new Set();
+  }
+  const gridNode = resolveReplaceComposeGridNode(targetNode);
+  if (!gridNode) {
+    return /* @__PURE__ */ new Set();
+  }
+  const replacedUids = /* @__PURE__ */ new Set();
+  for (const item of getSubModelList(gridNode, "items")) {
+    collectNodeAndDescendantUids(item, replacedUids);
+  }
+  const keys = /* @__PURE__ */ new Set();
+  context.keyMap.forEach((info, key) => {
+    if (replacedUids.has(info.uid)) {
+      keys.add(key);
+    }
+  });
+  return keys;
+}
+function buildExistingKeysForConflict(context, priorCreatedKeys, allowedExistingKeys) {
+  const existing = /* @__PURE__ */ new Set();
+  context.keyMap.forEach((_info, key) => {
+    if (!allowedExistingKeys.has(key)) {
+      existing.add(key);
+    }
+  });
+  priorCreatedKeys.forEach((key) => existing.add(key));
+  return existing;
+}
 async function compilePlanStep(actionName, step, index, context, deps, priorStepIds, priorCreatedKeys, options = {}) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+  var _a, _b, _c, _d, _e, _f, _g;
   const runtimeValues = step.action === "compose" ? (0, import_created_keys.normalizeComposeInlineKeysForPlan)(step.values || {}, `plan.steps[${index}].values`) : import_lodash.default.cloneDeep(step.values || {});
-  const payload = (0, import_step_link.replaceFlowSurfacePlanStepLinks)(
-    actionName,
-    runtimeValues,
-    `plan.steps[${index}].values`,
-    priorStepIds,
-    /* @__PURE__ */ new Set([...context.keyMap.keys(), ...priorCreatedKeys])
-  );
   const targetSelectorKey = (0, import_created_keys.isFlowSurfacePureKeyObject)((_a = step.selectors) == null ? void 0 : _a.target) ? String(step.selectors.target.key || "").trim() : void 0;
   const createdKeys = (0, import_created_keys.collectFlowSurfaceCreatedKeys)(step.action, step.values || {}, {
     targetSelectorKey
   });
-  (0, import_created_keys.assertNoDuplicateFlowSurfaceCreatedKeys)(createdKeys, `flowSurfaces ${actionName} plan.steps[${index}]`, {
-    existingKeys: [...context.keyMap.keys(), ...priorCreatedKeys],
-    reservedNames: [...priorStepIds, ...step.id ? [step.id] : []]
-  });
-  const compiled = {
-    index,
-    ...step.id ? { id: step.id } : {},
-    action: step.action,
-    payload,
-    resolvedSelectors: {},
-    usedKeys: [],
-    usedStepLinks: [],
-    createdKeys
-  };
-  const addUsedKey = (selector) => {
-    if ("summary" in selector) {
-      if (isFlowSurfaceResolvedStepLink(selector)) {
-        compiled.usedStepLinks.push(selector);
-      }
-      return selector.summary;
-    }
-    if (selector.source === "request" || selector.source === "declared") {
-      compiled.usedKeys.push(selector);
-    }
-    return {
-      uid: selector.uid,
-      kind: selector.kind,
-      ...selector.key ? { key: selector.key } : {},
-      source: selector.source
-    };
-  };
   const spec = (0, import_action_specs.getFlowSurfacePlanActionSpec)(step.action);
   if (!spec) {
     (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} plan.steps[${index}].action '${step.action}' is not supported`);
@@ -283,14 +380,14 @@ async function compilePlanStep(actionName, step, index, context, deps, priorStep
       `flowSurfaces ${actionName} plan.steps[${index}] action '${step.action}' does not support selectors.source`
     );
   }
-  if (spec.selectorMode === "none") {
-    compiled.payload = payload;
-  } else if (spec.selectorMode === "target") {
+  let resolvedTarget;
+  let resolvedSource;
+  if (selectorRequirements.requiresTarget) {
     const targetSelector = (_f = step.selectors) == null ? void 0 : _f.target;
     if (!targetSelector) {
       (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} plan.steps[${index}] requires selectors.target`);
     }
-    const target = await resolvePlanSelectorInContext(
+    resolvedTarget = await resolvePlanSelectorInContext(
       actionName,
       targetSelector,
       context,
@@ -300,59 +397,85 @@ async function compilePlanStep(actionName, step, index, context, deps, priorStep
       priorCreatedKeys,
       options
     );
-    compiled.payload = {
-      ...payload,
-      target: {
-        uid: buildSelectorRuntimeValue(target)
-      }
-    };
-    compiled.resolvedSelectors.target = addUsedKey(target);
-  } else if (spec.selectorMode === "rootUidTarget") {
-    const targetSelector = (_g = step.selectors) == null ? void 0 : _g.target;
-    if (!targetSelector) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} plan.steps[${index}] requires selectors.target`);
+  }
+  if (selectorRequirements.requiresSource) {
+    const sourceSelector = (_g = step.selectors) == null ? void 0 : _g.source;
+    if (!sourceSelector) {
+      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} plan.steps[${index}] requires selectors.source`);
     }
-    const target = await resolvePlanSelectorInContext(
+    resolvedSource = await resolvePlanSelectorInContext(
       actionName,
-      targetSelector,
+      sourceSelector,
       context,
       deps,
-      `plan.steps[${index}].selectors.target`,
+      `plan.steps[${index}].selectors.source`,
       priorStepIds,
       priorCreatedKeys,
       options
     );
+  }
+  assertReplaceComposeTargetSupportsScopeResolution(actionName, index, step, resolvedTarget);
+  const allowedExistingKeys = await collectReplaceScopeExistingKeys(step, context, resolvedTarget, deps, options);
+  (0, import_created_keys.assertNoDuplicateFlowSurfaceCreatedKeys)(createdKeys, `flowSurfaces ${actionName} plan.steps[${index}]`, {
+    existingKeys: buildExistingKeysForConflict(context, priorCreatedKeys, allowedExistingKeys),
+    reservedNames: [...priorStepIds, ...step.id ? [step.id] : []]
+  });
+  const payload = (0, import_step_link.replaceFlowSurfacePlanStepLinks)(
+    actionName,
+    runtimeValues,
+    `plan.steps[${index}].values`,
+    priorStepIds,
+    /* @__PURE__ */ new Set([...context.keyMap.keys(), ...priorCreatedKeys]),
+    allowedExistingKeys
+  );
+  const compiled = {
+    index,
+    ...step.id ? { id: step.id } : {},
+    action: step.action,
+    payload,
+    resolvedSelectors: {},
+    usedKeys: [],
+    usedStepLinks: [],
+    createdKeys
+  };
+  const addUsedKey = (selector) => {
+    if ("summary" in selector) {
+      if (isFlowSurfaceResolvedStepLink(selector)) {
+        compiled.usedStepLinks.push(selector);
+      }
+      return selector.summary;
+    }
+    if (selector.source === "request" || selector.source === "declared") {
+      compiled.usedKeys.push(selector);
+    }
+    return {
+      uid: selector.uid,
+      kind: selector.kind,
+      ...selector.key ? { key: selector.key } : {},
+      source: selector.source
+    };
+  };
+  if (spec.selectorMode === "none") {
+    compiled.payload = payload;
+  } else if (spec.selectorMode === "target") {
+    const target = resolvedTarget;
+    compiled.payload = {
+      ...payload,
+      target: {
+        uid: buildSelectorRuntimeValue(target)
+      }
+    };
+    compiled.resolvedSelectors.target = addUsedKey(target);
+  } else if (spec.selectorMode === "rootUidTarget") {
+    const target = resolvedTarget;
     compiled.payload = {
       ...payload,
       uid: buildSelectorRuntimeValue(target)
     };
     compiled.resolvedSelectors.target = addUsedKey(target);
   } else if (spec.selectorMode === "sourceTarget") {
-    const sourceSelector = (_h = step.selectors) == null ? void 0 : _h.source;
-    const targetSelector = (_i = step.selectors) == null ? void 0 : _i.target;
-    if (!sourceSelector || !targetSelector) {
-      (0, import_errors.throwBadRequest)(`flowSurfaces ${actionName} plan.steps[${index}] requires selectors.source and selectors.target`);
-    }
-    const source = await resolvePlanSelectorInContext(
-      actionName,
-      sourceSelector,
-      context,
-      deps,
-      `plan.steps[${index}].selectors.source`,
-      priorStepIds,
-      priorCreatedKeys,
-      options
-    );
-    const target = await resolvePlanSelectorInContext(
-      actionName,
-      targetSelector,
-      context,
-      deps,
-      `plan.steps[${index}].selectors.target`,
-      priorStepIds,
-      priorCreatedKeys,
-      options
-    );
+    const source = resolvedSource;
+    const target = resolvedTarget;
     compiled.payload = {
       ...payload,
       sourceUid: buildSelectorRuntimeValue(source),

package/dist/server/flow-surfaces/planning/key-registry.d.ts

@@ -26,7 +26,7 @@ export declare function buildSurfaceKeysObject(keyMap: Map<string, FlowSurfaceRe
     [k: string]: {
         uid: string;
         kind: string;
-        source: "declared" | "request" | "system";
+        source: "system" | "declared" | "request";
         locator: FlowSurfaceReadLocator;
     };
 };

package/dist/server/flow-surfaces/planning/runtime.js

@@ -152,6 +152,7 @@ async function compilePlanStep(actionName, step, index, context, deps, priorStep
     {
       normalizeGetTarget: deps.normalizeGetTarget,
       resolveLocator: deps.resolveLocator,
+      loadResolvedSurfaceTree: deps.loadResolvedSurfaceTree,
       buildPlanKeyKind: import_key_kind.buildPlanKeyKind
     },
     priorStepIds,