@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/cmd_properties.py

@@ -18,13 +18,10 @@ from .config import _api_call
 from .formatters import _extract_error_message, _is_api_success, _has_api_failure
 from .mutation_contract import mutation_contract, classify_mutation_result, combine_mutation_evidence
 from .skill_assets import asset_candidates
+from .property_policy_contract import PUBLISHED_SIMPLE_PROPERTIES as _PUBLISHED_SIMPLE_PROPERTIES
 
 # ─── 属性设置 API ──────────────────────────────────────────────────────────────
 
-_PUBLISHED_SIMPLE_PROPERTIES = frozenset({
-    "mustinput", "defvalue", "maxlength", "precision", "scale", "invisible",
-    "width", "height",
-})
 
 # Some field families render a scalar property through a dialog editor.  The
 # domain model therefore labels the designer surface "complex", but the field
@@ -571,6 +568,16 @@ def _describe_one_property(declaration, indexed, verified, element_type=None):
         out["guidance"] = "the platform declares this property not editable; do not attempt a write"
         return out
 
+    if declaration.get("propertyName") == "DropdownItems":
+        out["inputFormat"] = "menuEditIntent"
+        out["guidance"] = (
+            "Use configureDropdownMenu with append/update/remove/order/moves intent. "
+            "It resolves the live menu and preserves existing identities; do not submit "
+            "the read projection as a replacement or clear/rebuild after failure. "
+            "Its command schema defines the input."
+        )
+        return out
+
     if declaration.get("propertyName") in _SCALAR_PROPERTIES_WITH_COMPLEX_EDITOR:
         out.pop("complexType", None)
         out["inputFormat"] = "scalarViaSetProperties"
@@ -1035,6 +1042,12 @@ def _normalize_recorded_complex_properties(properties):
     normalized = {}
     for selector, value in properties.items():
         wanted = str(selector or "").strip().casefold()
+        if wanted == "lock":
+            raise ValueError(
+                "PROPERTY_POLICY_LOCK_SHAPE_INVALID: Lock belongs in policy.set, "
+                "for example {\"set\":{\"Lock\":\"new,edit,submit,audit\"}}; "
+                "do not use policy.complex or infer support from the read-only designer schema"
+            )
         matches = [
             name for name in _PROPERTY_POLICY_COMPLEX_TYPES
             if wanted in {
@@ -5145,6 +5158,12 @@ def do_set_complex_property(cfg, token, form_number, complex_type, data, element
     rejection = _assert_known_complex_type(complex_type)
     if rejection is not None:
         return rejection
+    if complex_type == "dropdownItems":
+        return {
+            "status": False, "errorCode": "DROPDOWN_MENU_EDIT_REQUIRED",
+            "message": "Use configureDropdownMenu with targeted edits so existing IDs and unmentioned items are retained.",
+            "writeAttempted": False,
+        }
     data = _normalize_complex_payload(complex_type, data)
     rejection = _assert_complex_payload_shape(complex_type, data)
     if rejection is not None:
@@ -5592,6 +5611,649 @@ def _set_candidate_backed_property(
     return result if verified else _mark_unknown_after_write(result)
 
 
+_DROPDOWN_ITEM_FIELDS = {
+    "Key", "Title", "SubTitle", "OperationKey", "Background", "ImageKey",
+    "IsSwitch", "IsTheme", "IsMerge", "Lock", "Visible", "Uploadable",
+    "UploadConfig", "Id", "Index",
+}
+_DROPDOWN_ALIASES = {
+    "key": "Key", "title": "Title", "subtitle": "SubTitle",
+    "operationkey": "OperationKey", "operation": "OperationKey",
+    "background": "Background", "imagekey": "ImageKey", "icon": "ImageKey",
+    "isswitch": "IsSwitch", "switch": "IsSwitch", "istheme": "IsTheme",
+    "theme": "IsTheme", "ismerge": "IsMerge", "merge": "IsMerge",
+    "lock": "Lock", "visible": "Visible", "uploadable": "Uploadable",
+    "uploadconfig": "UploadConfig", "id": "Id", "index": "Index",
+    "isv": "Isv", "isvflag": "Isv",
+}
+_DROPDOWN_STATES = {
+    "初始": "init", "新增": "new", "修改": "edit", "查看": "view",
+    "提交": "submit", "审核": "audit",
+}
+
+
+def _dropdown_items_value(cfg, token, form_number, element_key):
+    read = do_get_properties(cfg, token, form_number, element_key, ["DropdownItems"])
+    if not _is_api_success(read):
+        return None, read
+    values = read.get("data") or {}
+    actual = next((value for key, value in values.items()
+                   if str(key).casefold() == "dropdownitems"), None)
+    if actual is None:
+        return None, {
+            "status": False, "errorCode": "DROPDOWN_MENU_READ_UNAVAILABLE",
+            "message": "DropdownItems was not returned; missing data is not an empty menu",
+            "writeAttempted": False,
+        }
+    actual = _decode_jsonish(actual)
+    if actual in (None, ""):
+        actual = []
+    if not isinstance(actual, list) or not all(isinstance(item, dict) for item in actual):
+        return None, {
+            "status": False, "errorCode": "DROPDOWN_MENU_READ_INVALID",
+            "message": "DropdownItems read-back is not an item array",
+            "writeAttempted": False, "data": {"actual": actual},
+        }
+    try:
+        items = [_dropdown_authored_item(item) for item in actual]
+        keys = [item.get("Key") for item in items]
+        if any(not key for key in keys) or len(keys) != len(set(keys)):
+            raise ValueError("current menu identities are missing or duplicated")
+        return items, None
+    except ValueError as exc:
+        return None, {
+            "status": False, "errorCode": "DROPDOWN_MENU_PRESERVATION_UNAVAILABLE",
+            "message": str(exc), "writeAttempted": False,
+        }
+
+
+def _dropdown_authored_item(item):
+    """Adapt MetaPropertyService JavaBeans to DropdownMenuEditPlugin's authored fields."""
+    result = {}
+    for raw_key, value in item.items():
+        if raw_key == "_Type_" and value == "DropdownItem":
+            continue
+        if str(raw_key).casefold() == "visiblevalue":
+            # Derived bitmask from getVisibleValue(), not an authored property.
+            continue
+        key = _DROPDOWN_ALIASES.get(str(raw_key).replace("_", "").casefold())
+        # Read-back is a preservation baseline, not a write payload. Snapshot
+        # editing retains the native objects by ID and patches only selected values.
+        key = key or raw_key
+        if value is not None:
+            result[key] = value
+    for key in ("Visible", "Lock"):
+        if key in result:
+            result[key] = ",".join(sorted(set(
+                part.strip() for part in result[key].split(",") if part.strip())))
+    if "UploadConfig" in result:
+        result["UploadConfig"] = _dropdown_upload_config(result["UploadConfig"], readback=True)
+    return result
+
+
+def _dropdown_mismatches(expected, actual, path="DropdownItems"):
+    """Identity and authored text comparisons must remain case-sensitive."""
+    if isinstance(expected, str) and isinstance(actual, dict) and path.rsplit(".", 1)[-1] in ("Title", "SubTitle"):
+        if expected in [value for key, value in actual.items() if key != "resId"]:
+            return []
+    if isinstance(expected, dict) and isinstance(actual, dict):
+        return [mismatch for key, value in expected.items()
+                for mismatch in _dropdown_mismatches(value, actual.get(key), f"{path}.{key}")]
+    if isinstance(expected, list) and isinstance(actual, list) and len(expected) == len(actual):
+        return [mismatch for index, value in enumerate(expected)
+                for mismatch in _dropdown_mismatches(value, actual[index], f"{path}[{index}]")]
+    if path.endswith((".Visible", ".Lock")) and isinstance(expected, str) and isinstance(actual, str):
+        expected = set(filter(None, expected.split(",")))
+        actual = set(filter(None, actual.split(",")))
+    if expected == actual:
+        return []
+    return [{"property": path, "expected": sorted(expected) if isinstance(expected, set) else expected,
+             "actual": sorted(actual) if isinstance(actual, set) else actual}]
+
+
+def _dropdown_upload_config(value, *, readback=False):
+    value = _decode_jsonish(value)
+    if not isinstance(value, dict):
+        raise ValueError("DROPDOWN_MENU_UPLOAD_CONFIG_INVALID: object required")
+    aliases = {
+        "multiple": "Multiple", "suffix": "Suffix", "accept": "Suffix",
+        "limitcount": "LimitCount", "maxfiles": "LimitCount",
+        "limitsize": "LimitSize", "maxfilesize": "LimitSize", "url": "Url",
+    }
+    result = {}
+    for raw_key, field in value.items():
+        if raw_key == "_Type_" and value[raw_key] == "UploadOption":
+            continue
+        key = aliases.get(str(raw_key).replace("_", "").casefold())
+        if readback:
+            # Native UploadOption has more fields than the published authoring
+            # input. Keep that state, including unknown/default/null values.
+            key = key or str(raw_key).casefold()
+            if key in result and result[key] != field:
+                raise ValueError(f"DROPDOWN_MENU_UPLOAD_CONFIG_AMBIGUOUS: {raw_key}")
+            result[key] = copy.deepcopy(field)
+            continue
+        if key in result and result[key] == field:
+            continue
+        if key is None or key in result:
+            raise ValueError(f"DROPDOWN_MENU_UPLOAD_CONFIG_UNKNOWN_OR_DUPLICATE: {raw_key}")
+        if key == "Multiple" and not isinstance(field, bool):
+            raise ValueError("DROPDOWN_MENU_UPLOAD_CONFIG_INVALID: Multiple requires boolean")
+        if key in ("LimitCount", "LimitSize") and (
+                isinstance(field, bool) or not isinstance(field, int) or field < 0):
+            raise ValueError(f"DROPDOWN_MENU_UPLOAD_CONFIG_INVALID: {key} requires nonnegative integer")
+        if key in ("Suffix", "Url") and not isinstance(field, str):
+            raise ValueError(f"DROPDOWN_MENU_UPLOAD_CONFIG_INVALID: {key} requires string")
+        result[key] = field
+    return result
+
+
+def _normalize_dropdown_item(item, *, partial=False):
+    if not isinstance(item, dict):
+        raise ValueError("DROPDOWN_MENU_ITEM_INVALID: every item must be an object")
+    normalized = {}
+    for raw_key, value in item.items():
+        key = _DROPDOWN_ALIASES.get(str(raw_key).replace("_", "").casefold())
+        if key is None or key not in _DROPDOWN_ITEM_FIELDS:
+            raise ValueError(f"DROPDOWN_MENU_ITEM_UNKNOWN: {raw_key}")
+        if key in normalized:
+            raise ValueError(f"DROPDOWN_MENU_ITEM_DUPLICATE: {raw_key}")
+        if key in ("Id", "Index"):
+            raise ValueError(f"DROPDOWN_MENU_ITEM_IDENTITY_OWNED: {raw_key}")
+        normalized[key] = value
+    if not partial and not str(normalized.get("Key") or "").strip():
+        raise ValueError("DROPDOWN_MENU_ITEM_KEY_REQUIRED")
+    for name in ("Key", "Title", "SubTitle", "OperationKey", "Background", "ImageKey"):
+        if name in normalized and not isinstance(normalized[name], str):
+            raise ValueError(f"DROPDOWN_MENU_ITEM_STRING_REQUIRED: {name}")
+    for name in ("Visible", "Lock"):
+        value = normalized.get(name)
+        if isinstance(value, (list, str)):
+            parts = value if isinstance(value, list) else value.split(",")
+            normalized[name] = ",".join(sorted({
+                _DROPDOWN_STATES.get(str(part).strip(), str(part).strip())
+                for part in parts if str(part).strip()
+            }))
+            allowed = {"init", "new", "edit", "view", "submit", "audit"}
+            if name == "Lock":
+                allowed.discard("init")
+            if set(normalized[name].split(",")) - allowed - {""}:
+                raise ValueError(f"DROPDOWN_MENU_STATE_INVALID: {name}")
+    for name in ("IsSwitch", "IsTheme", "IsMerge", "Uploadable"):
+        if name in normalized and not isinstance(normalized[name], bool):
+            raise ValueError(f"DROPDOWN_MENU_ITEM_BOOLEAN_REQUIRED: {name}")
+    if "UploadConfig" in normalized:
+        normalized["UploadConfig"] = _dropdown_upload_config(normalized["UploadConfig"])
+    if normalized.get("Uploadable") is True and str(normalized.get("OperationKey") or ""):
+        raise ValueError("DROPDOWN_MENU_UPLOAD_OPERATION_CONFLICT")
+    return normalized
+
+
+def _dropdown_target(items, selector):
+    """Resolve an exact key first, then one unique ID, title or operation key."""
+    value = str(selector or "").strip()
+    exact = [item for item in items if item.get("Key") == value]
+    matches = exact or [item for item in items if value and (
+        value in (item.get("Id"), item.get("Title"), item.get("OperationKey"))
+        or isinstance(item.get("Title"), dict) and value in item["Title"].values())]
+    if len(matches) != 1:
+        raise ValueError(
+            f"DROPDOWN_MENU_TARGET_{'AMBIGUOUS' if matches else 'NOT_FOUND'}: {value}")
+    return matches[0]
+
+
+
+def _dropdown_full_document(result):
+    if not _is_api_success(result) or not isinstance(result.get("data"), dict):
+        return None
+    document = copy.deepcopy(result["data"])
+    for key in ("formmeta", "entitymeta"):
+        document[key] = _decode_jsonish(document.get(key))
+        if not isinstance(document[key], dict):
+            return None
+    return document
+
+
+def _dropdown_apply_locale_value(document, item_id, property_name, value, requested_locale,
+                                 *, create_prefix=None):
+    """Update one existing locale resource and return its exact JSON pointer."""
+    rows = ((document.get("localeItems") or {}).get("form")) or []
+    suffix = f".DropdownItems.{item_id}.{property_name}"
+    matches = []
+    for index, row in enumerate(rows):
+        if not isinstance(row, dict):
+            continue
+        for resource_key, resource in row.items():
+            if not isinstance(resource, dict):
+                continue
+            identity = str(resource.get("resId") or resource_key)
+            if identity.endswith(suffix):
+                matches.append((index, resource_key, resource))
+    if not matches and create_prefix:
+        known = {name for row in rows if isinstance(row, dict)
+                 for resource in row.values() if isinstance(resource, dict)
+                 for name in resource if name != "resId"}
+        selected = requested_locale or document["formmeta"].get("Language")
+        if not selected and len(known) == 1:
+            selected = next(iter(known))
+        if not selected:
+            return None, {
+                "status": False, "errorCode": "DROPDOWN_MENU_LOCALE_REQUIRED",
+                "message": "Choose a language key for the new menu text with --locale.",
+                "writeAttempted": False, "retryable": False,
+                "data": {"itemId": item_id, "property": property_name,
+                         "locales": sorted(known), "argument": "--locale"},
+            }
+        resource_key = f"{create_prefix}.DropdownItems.{item_id}.{property_name}"
+        resource = {"resId": resource_key, selected: value}
+        rows.append({resource_key: resource})
+        matches = [(len(rows) - 1, resource_key, resource)]
+    if len(matches) != 1:
+        return None, {
+            "status": False, "errorCode": "DROPDOWN_MENU_LOCALE_RESOURCE_UNAVAILABLE",
+            "message": "The selected menu text has no unique locale resource; nothing was written.",
+            "writeAttempted": False, "retryable": False,
+            "data": {"itemId": item_id, "property": property_name,
+                     "resourceMatches": len(matches)},
+        }
+    index, resource_key, resource = matches[0]
+    locales = [name for name in resource if name != "resId"]
+    selected = requested_locale if requested_locale in locales else None
+    if selected is None and len(locales) == 1:
+        selected = locales[0]
+    if selected is None:
+        return None, {
+            "status": False, "errorCode": "DROPDOWN_MENU_LOCALE_REQUIRED",
+            "message": "Choose one returned language key and retry the same intent with --locale.",
+            "writeAttempted": False, "retryable": False,
+            "data": {"itemId": item_id, "property": property_name,
+                     "locales": locales, "argument": "--locale"},
+        }
+    resource[selected] = value
+    escape = lambda token: str(token).replace("~", "~0").replace("/", "~1")
+    return f"/localeItems/form/{index}/{escape(resource_key)}/{escape(selected)}", None
+
+def _dropdown_snapshot_edit(cfg, token, form_number, element_key, current, desired, *, locale=None):
+    """Preserve native objects through the existing full-snapshot API, scoped to one menu."""
+    import pathlib
+    import tempfile
+    import uuid
+    from .cmd_listui import do_load_full_metadata, do_save_full_metadata
+
+    def fail(code, message, **details):
+        return {"status": False, "errorCode": code, "message": message,
+                "writeAttempted": False, "retryable": False, "data": details}
+
+    schema = do_get_property_schema(cfg, token, form_number, element_key)
+    if not _is_api_success(schema):
+        return fail("DROPDOWN_MENU_SCHEMA_UNAVAILABLE", "Cannot verify the menu's editable surface.", cause=schema)
+    declarations = [row for row in schema.get("data") or []
+                    if str(row.get("propertyName", "")).casefold() == "dropdownitems"]
+    if len(declarations) != 1 or declarations[0].get("editable") is not True:
+        return fail("DROPDOWN_MENU_NOT_EDITABLE", "The live designer does not declare this menu editable.",
+                    declarations=declarations)
+
+    loaded = do_load_full_metadata(cfg, token, form_number)
+    before = _dropdown_full_document(loaded)
+    if before is None:
+        return fail("DROPDOWN_MENU_SNAPSHOT_UNAVAILABLE",
+                    "A complete form+entity snapshot is required for lossless menu editing. Other metadata commands remain available.",
+                    cause=loaded)
+    if str(before["formmeta"].get("Key") or "") != form_number:
+        return fail("DROPDOWN_MENU_SNAPSHOT_TARGET_MISMATCH", "Snapshot does not match the bound form.")
+    matches = [(index, item) for index, item in enumerate(before["formmeta"].get("Items") or [])
+               if isinstance(item, dict) and item.get("Key") == element_key]
+    if len(matches) != 1:
+        return fail("DROPDOWN_MENU_TARGET_AMBIGUOUS", "No unique button exists in the primary form layout.")
+    position, button = matches[0]
+    raw_menu = _decode_jsonish(button.get("DropdownItems", []))
+    if not isinstance(raw_menu, list) or not all(isinstance(row, dict) for row in raw_menu):
+        return fail("DROPDOWN_MENU_SNAPSHOT_INVALID", "The authored menu is not an object array.")
+    pairs = [(row.get("Id"), row.get("Key")) for row in raw_menu]
+    if pairs != [(row.get("Id"), row.get("Key")) for row in current]:
+        return fail("DROPDOWN_MENU_BASELINE_CHANGED", "Menu identities or order changed after resolution; refresh this menu.")
+    # Compare shared authored fields as well; full metadata omits default-valued fields.
+    for raw, baseline in zip(raw_menu, current):
+        shared = {key: value for key, value in _dropdown_authored_item(raw).items()
+                  if key in baseline and key != "Index"}
+        if _dropdown_mismatches(shared, baseline):
+            return fail("DROPDOWN_MENU_BASELINE_CHANGED", "Menu properties changed after resolution; refresh this menu.")
+
+    source_by_key = {row["Key"]: row for row in raw_menu}
+    current_by_key = {row["Key"]: row for row in current}
+    owner = before["entitymeta"].get("IsvFlag") or before["formmeta"].get("IsvFlag") or before.get("isv")
+    edited = []
+    locale_updates = []
+    for item in desired:
+        source = source_by_key.get(item["Key"])
+        if source is None:
+            if not owner:
+                return fail("DROPDOWN_MENU_OWNER_UNRESOLVED", "Snapshot does not identify the developer for new menu items.")
+            native = {"_Type_": "DropdownItem", "Id": uuid.uuid4().hex,
+                      "IsvFlag": owner, "Key": item["Key"]}
+            changes = item
+        else:
+            native = copy.deepcopy(source)
+            changes = {key: value for key, value in item.items()
+                       if key not in ("Id", "Isv") and _dropdown_mismatches(
+                           value, current_by_key[item["Key"]].get(key), key)}
+        for key, value in changes.items():
+            if key in ("Id", "Isv"):
+                continue
+            if key in ("Title", "SubTitle") and isinstance(value, str):
+                selected_locale = locale or cfg.get("locale")
+                if isinstance(native.get(key), dict):
+                    locales = [name for name in native[key] if name != "resId"]
+                    if selected_locale not in locales:
+                        if selected_locale or len(locales) != 1:
+                            return fail("DROPDOWN_MENU_LOCALE_REQUIRED",
+                                        "Choose one returned language key and retry the same intent with --locale.",
+                                        locales=locales, itemKey=item["Key"], argument="--locale")
+                        selected_locale = locales[0]
+                    native[key][selected_locale] = value
+                else:
+                    native[key] = value
+                    locale_updates.append((
+                        native.get("Id"), key, value, selected_locale,
+                        ".".join(filter(None, (
+                            str(before.get("appNum") or ""), str(before["formmeta"].get("Id") or ""),
+                            str(button.get("Id") or "")))) or None,
+                    ))
+            elif key == "UploadConfig":
+                raw_config = native.get(key)
+                merged = copy.deepcopy(_decode_jsonish(raw_config)) if raw_config is not None else {}
+                if not isinstance(merged, dict):
+                    return fail("DROPDOWN_MENU_UPLOAD_CONFIG_INVALID", "Authored upload configuration is not an object.")
+                baseline = current_by_key.get(item["Key"], {}).get("UploadConfig", {})
+                for field, setting in value.items():
+                    if field in baseline and baseline[field] == setting:
+                        continue
+                    actual_key = next((name for name in merged
+                        if field in _dropdown_upload_config({name: merged[name]}, readback=True)), field)
+                    merged[actual_key] = copy.deepcopy(setting)
+                native[key] = json.dumps(merged, ensure_ascii=False) if isinstance(raw_config, str) else merged
+            else:
+                native[key] = copy.deepcopy(value)
+        native["Index"] = item["Index"]
+        edited.append(native)
+    after = copy.deepcopy(before)
+    after["formmeta"]["Items"][position]["DropdownItems"] = edited
+    pointer = f"/formmeta/Items/{position}/DropdownItems"
+    locale_paths = set()
+    for item_id, property_name, value, selected_locale, create_prefix in locale_updates:
+        locale_path, locale_error = _dropdown_apply_locale_value(
+            after, item_id, property_name, value, selected_locale,
+            create_prefix=create_prefix)
+        if locale_error is not None:
+            return locale_error
+        locale_paths.add(locale_path)
+    changed = _instant_sync_changed_pointers(before, after)
+    locale_list_changed = len(((before.get("localeItems") or {}).get("form")) or []) != len(
+        ((after.get("localeItems") or {}).get("form")) or [])
+    if any(path not in locale_paths
+           and not (locale_list_changed and path == "/localeItems/form")
+           and path != pointer and not path.startswith(pointer + "/") for path in changed):
+        return fail("DROPDOWN_MENU_DIFF_SCOPE_MISMATCH", "Proposed changes exceed the selected menu.")
+
+    # Preserve source serialization for API versions returning JSON-encoded sections.
+    payload = copy.deepcopy(loaded["data"])
+    payload["formmeta"] = (json.dumps(after["formmeta"], ensure_ascii=False)
+                           if isinstance(payload["formmeta"], str) else after["formmeta"])
+    if locale_paths:
+        payload["localeItems"] = copy.deepcopy(after["localeItems"])
+    directory = pathlib.Path(tempfile.mkdtemp(prefix="cosmic-dropdown-"))
+    snapshot = directory / "before.json"
+    snapshot.write_text(json.dumps(loaded["data"], ensure_ascii=False, indent=2), encoding="utf-8")
+    fresh = do_load_full_metadata(cfg, token, form_number)
+    if _dropdown_full_document(fresh) != before:
+        return fail("DROPDOWN_MENU_BASELINE_CHANGED", "The form changed before saving; no write was sent.",
+                    beforeSnapshot=str(snapshot))
+    result = do_save_full_metadata(cfg, token, form_number, payload, allow_full_replace=True)
+    if not _is_api_success(result):
+        result = dict(result)
+        result.setdefault("data", {})
+        if not isinstance(result["data"], dict):
+            result["data"] = {}
+        result["data"]["beforeSnapshot"] = str(snapshot)
+        return result
+    readback = do_load_full_metadata(cfg, token, form_number)
+    actual = _dropdown_full_document(readback)
+    differences = _instant_sync_changed_pointers(after, actual) if actual is not None else {"/"}
+    # Only server-managed audit fields are exempt; layout, rules, operations and
+    # other business metadata are all included in this independent comparison.
+    differences -= {"/modifyDate", "/modifierId"}
+    if actual is not None:
+        (directory / "after.json").write_text(
+            json.dumps(readback["data"], ensure_ascii=False, indent=2), encoding="utf-8")
+    verified = not differences
+    result.update(status=verified, errorCode="0" if verified else "DROPDOWN_MENU_SNAPSHOT_READBACK_MISMATCH",
+                  message="Menu edited and full snapshot verified." if verified
+                          else "The saved snapshot differs from the intended result; inspect before another write.",
+                  writeAttempted=True,
+                  verification={"verified": verified, "readPath": "loadFullMetadata",
+                                "changedMenuPath": pointer, "changedLocalePaths": sorted(locale_paths),
+                                "unexpectedPaths": sorted(differences)[:30]},
+                  data={"beforeSnapshot": str(snapshot), "changed": True if verified else None})
+    return result if verified else _mark_unknown_after_write(result)
+
+def _resolve_dropdown_parent(cfg, token, form_number, intent):
+    from .cmd_listui import do_load_full_metadata
+
+    document = _dropdown_full_document(do_load_full_metadata(cfg, token, form_number))
+    if document is None:
+        return None, {"status": False, "errorCode": "DROPDOWN_MENU_SNAPSHOT_UNAVAILABLE",
+                      "message": "Cannot resolve a menu without a complete live form snapshot.",
+                      "writeAttempted": False}
+    appended = {item.get("key") or item.get("Key") for item in intent.get("append", []) if isinstance(item, dict)}
+    selectors = [item.get("key") or item.get("Key") for item in intent.get("update", []) if isinstance(item, dict)]
+    selectors += [item.get("key") or item.get("Key") if isinstance(item, dict) else item
+                  for item in intent.get("remove", [])]
+    selectors += list(intent.get("order", []))
+    selectors += [item.get(key) for item in intent.get("moves", []) if isinstance(item, dict)
+                  for key in ("key", "before", "after") if item.get(key)]
+    selectors = [selector for selector in selectors if selector and selector not in appended]
+    candidates, matches = [], []
+    for control in document["formmeta"].get("Items", []):
+        if not isinstance(control, dict) or "DropdownItems" not in control:
+            continue
+        raw = _decode_jsonish(control["DropdownItems"])
+        if not isinstance(raw, list):
+            continue
+        candidate = {"key": control.get("Key"), "name": control.get("Name")}
+        candidates.append(candidate)
+        if not selectors:
+            continue
+        try:
+            items = [_dropdown_authored_item(item) for item in raw]
+            for selector in selectors:
+                _dropdown_target(items, selector)
+        except ValueError:
+            continue
+        matches.append(candidate)
+    if len(matches) == 1 and matches[0]["key"]:
+        return matches[0]["key"], None
+    return None, {
+        "status": False, "errorCode": "DROPDOWN_MENU_PARENT_REQUIRED",
+        "message": "Pass --element with the intended button; menu items do not identify one unique parent.",
+        "writeAttempted": False, "data": {"candidates": matches or candidates, "argument": "--element"},
+    }
+
+def do_configure_dropdown_menu(cfg, token, form_number, element_key, intent, *, locale=None):
+    """Stage edits on the current menu and save once, as the designer dialog does."""
+    if not isinstance(intent, dict) or not intent:
+        raise ValueError("DROPDOWN_MENU_INPUT_INVALID")
+    allowed = {"append", "update", "remove", "order", "moves"}
+    if set(intent) - allowed:
+        return {
+            "status": False, "errorCode": "DROPDOWN_MENU_INTENT_UNSUPPORTED",
+            "message": "Use targeted edits. Clearing or replacing the menu is not an edit recovery strategy.",
+            "writeAttempted": False,
+        }
+    if any(not isinstance(value, list) for value in intent.values()):
+        raise ValueError("DROPDOWN_MENU_INPUT_INVALID: edit actions require arrays")
+    if not element_key:
+        element_key, error = _resolve_dropdown_parent(cfg, token, form_number, intent)
+        if error is not None:
+            return error
+    current, error = _dropdown_items_value(cfg, token, form_number, element_key)
+    if error is not None:
+        return error
+    desired = copy.deepcopy(current)
+    changed_operations = set()
+    try:
+        appended = set()
+        for raw in intent.get("append", []):
+            item = _normalize_dropdown_item(raw)
+            key = item["Key"]
+            if any(row.get("Key") == key for row in desired):
+                raise ValueError(f"DROPDOWN_MENU_APPEND_KEY_EXISTS: {key}; use update to edit it")
+            desired.append(item)
+            appended.add(key)
+            if item.get("OperationKey"):
+                changed_operations.add(item["OperationKey"])
+        updated = set()
+        for raw in intent.get("update", []):
+            patch = _normalize_dropdown_item(raw)
+            target = _dropdown_target(desired, patch.pop("Key"))
+            key = target["Key"]
+            if key in updated:
+                raise ValueError(f"DROPDOWN_MENU_DUPLICATE_UPDATE: {key}")
+            updated.add(key)
+            if "UploadConfig" in patch:
+                patch["UploadConfig"] = {
+                    **target.get("UploadConfig", {}), **patch["UploadConfig"],
+                }
+            if patch.get("OperationKey") and patch["OperationKey"] != target.get("OperationKey"):
+                changed_operations.add(patch["OperationKey"])
+            for name, value in patch.items():
+                previous = target.get(name)
+                if name in ("Title", "SubTitle") and isinstance(previous, dict):
+                    language = locale or cfg.get("locale")
+                    texts = {key: text for key, text in previous.items() if key != "resId"}
+                    if language and texts.get(language) == value:
+                        continue
+                    if not language and len(texts) == 1 and value in texts.values():
+                        continue
+                elif not _dropdown_mismatches(value, previous, name):
+                    continue
+                target[name] = value
+        removed = set()
+        for selector in intent.get("remove", []):
+            if isinstance(selector, dict):
+                selector = selector.get("key") or selector.get("Key")
+            key = _dropdown_target(desired, selector)["Key"]
+            if key in appended or key in updated:
+                raise ValueError(f"DROPDOWN_MENU_CONFLICTING_EDIT: {key}")
+            removed.add(key)
+        desired = [item for item in desired if item["Key"] not in removed]
+        if "order" in intent and "moves" in intent:
+            raise ValueError("DROPDOWN_MENU_ORDER_MODE_CONFLICT")
+        if "order" in intent:
+            ordered = [_dropdown_target(desired, selector) for selector in intent["order"]]
+            keys = {item["Key"] for item in ordered}
+            if len(keys) != len(ordered):
+                raise ValueError("DROPDOWN_MENU_ORDER_MISMATCH: each selected item must appear once")
+            desired = ordered + [item for item in desired if item["Key"] not in keys]
+        for move in intent.get("moves", []):
+            if not isinstance(move, dict) or set(move) - {"key", "before", "after"}:
+                raise ValueError("DROPDOWN_MENU_MOVE_INVALID")
+            anchors = set(move) & {"before", "after"}
+            if len(anchors) != 1:
+                raise ValueError("DROPDOWN_MENU_MOVE_INVALID: supply one before/after anchor")
+            anchor_name = next(iter(anchors))
+            item = _dropdown_target(desired, move.get("key"))
+            anchor = _dropdown_target(desired, move[anchor_name])
+            if item is anchor:
+                raise ValueError("DROPDOWN_MENU_MOVE_INVALID: item is its own anchor")
+            desired.remove(item)
+            desired.insert(desired.index(anchor) + (anchor_name == "after"), item)
+        for item in desired:
+            if item.get("Uploadable") and item.get("OperationKey"):
+                raise ValueError("DROPDOWN_MENU_UPLOAD_OPERATION_CONFLICT")
+        if desired == current:
+            return {
+                "status": True, "errorCode": "0", "message": "Menu already matches",
+                "data": {"changed": False, "formNumber": form_number, "elementKey": element_key},
+                "verification": {"verified": True, "readPath": "getProperties.DropdownItems"},
+            }
+        if any(not item.get("Id") for item in current):
+            raise ValueError("DROPDOWN_MENU_ID_MISSING: cannot preserve original item identity")
+        if len({item["Id"] for item in current}) != len(current):
+            raise ValueError("DROPDOWN_MENU_ID_DUPLICATE: cannot preserve original item identity")
+    except ValueError as exc:
+        return {
+            "status": False, "errorCode": str(exc).split(":")[0],
+            "message": str(exc), "writeAttempted": False,
+            "data": {"candidates": [
+                {key: item.get(key) for key in ("Key", "Title", "OperationKey")}
+                for item in current
+            ]},
+        }
+    if changed_operations:
+        from .cmd_operations import do_list_operations
+        operation_result = do_list_operations(cfg, token, form_number)
+        if not _is_api_success(operation_result):
+            return {
+                "status": False, "errorCode": "DROPDOWN_MENU_OPERATION_READ_FAILED",
+                "message": "Cannot verify changed operation bindings; nothing was written",
+                "writeAttempted": False, "data": {"cause": operation_result},
+            }
+        data = operation_result.get("data") or []
+        rows = data.get("operations", []) if isinstance(data, dict) else data
+        operations = {str(row.get("operationKey") or "") for row in rows if isinstance(row, dict)}
+        missing = sorted(changed_operations - operations)
+        if missing:
+            return {
+                "status": False, "errorCode": "DROPDOWN_MENU_OPERATION_NOT_FOUND",
+                "message": "Bind an existing implemented operation; a placeholder does not implement menu behavior.",
+                "writeAttempted": False, "data": {"missingOperationKeys": missing},
+            }
+        unresolved = [
+            row for row in rows if row.get("operationKey") in changed_operations
+            and (not row.get("operationType")
+                 or row.get("operationType") == "donothing" and not (
+                     row.get("pluginCount") or row.get("opBizRuleCount")))
+        ]
+        if unresolved:
+            return {
+                "status": False, "errorCode": "DROPDOWN_MENU_OPERATION_IMPLEMENTATION_REQUIRED",
+                "message": "Menu binding exists but has no demonstrated executable implementation.",
+                "writeAttempted": False, "retryable": False,
+                "data": {"operations": [{
+                    "key": row.get("operationKey"), "type": row.get("operationType"),
+                    "pluginCount": row.get("pluginCount", 0),
+                    "businessRuleCount": row.get("opBizRuleCount", 0),
+                } for row in unresolved]},
+                "recovery": {"action": "implement_or_select_operation",
+                             "message": "Implement the requested behavior or select an existing implemented operation, then retry the same menu intent."},
+            }
+    for index, item in enumerate(desired, 1):
+        item["Index"] = index
+    result = _dropdown_snapshot_edit(cfg, token, form_number, element_key, current, desired, locale=locale)
+    if isinstance(result, dict):
+        if not _is_api_success(result):
+            action = {
+                "DROPDOWN_MENU_BASELINE_CHANGED": "refresh_menu_and_reapply_intent",
+                "DROPDOWN_MENU_SNAPSHOT_UNAVAILABLE": "check_full_metadata_api_availability",
+                "DROPDOWN_MENU_NOT_EDITABLE": "check_designer_editability",
+                "DROPDOWN_MENU_LOCALE_REQUIRED": "select_title_locale",
+                "DROPDOWN_MENU_SNAPSHOT_READBACK_MISMATCH": "compare_recovery_snapshots",
+            }.get(result.get("errorCode"), "inspect_menu_edit_failure")
+            result["recovery"] = {
+                "automaticRetry": False,
+                "action": action,
+                "message": result.get("message"),
+                "scope": {"formNumber": form_number, "elementKey": element_key},
+            }
+        if not isinstance(result.get("data"), dict):
+            result["data"] = {}
+        result["data"].update({
+            "formNumber": form_number, "elementKey": element_key,
+            "changed": True if _is_api_success(result) else None,
+        })
+    return result
+
+
 def do_set_org_funcs(cfg, token, form_number, element_key, data):
     """Resolve a live org-function name/code, write it, then independently read it back."""
     resolved, error = _resolve_org_func(