PropertyMovement.h header

std::unique_ptr< ew::core::undo::Command > ew::app::entity::buildDemoteFieldCommand(ew::core::project::Project &project, ew::core::foundation::CategoryId categoryId, const QString &key)

A command that moves the property key OFF category categoryId and onto each entity that holds a value for it, or nullptr when the category has no such field of its own.

Every entity that would be left with a value it can no longer see gets the definition, so the data stays reachable. Entities with no value get nothing – the property was never about them, which is the whole reason it is being demoted.

std::unique_ptr< ew::core::undo::Command > ew::app::entity::buildPromoteFieldCommand(ew::core::project::Project &project, ew::core::foundation::ContentId entityId, const QString &key)

A command that moves the property key OFF entity entityId and onto its category, or nullptr when the entity does not hold such a property of its own.

The reverse of demoting, and the deliberate way to say "this turned out to be shared after all". Every sibling in the category gains the property; none gains a VALUE, since the values were never theirs.

std::vector< ew::core::foundation::ContentId > ew::app::entity::entitiesHoldingValueFor(const ew::core::project::Project &project, ew::core::foundation::CategoryId categoryId, QStringView key)

Moving one property between a category and the entities under it, as a single undoable step.

The two directions the whole cleanup is made of, and the primitives the migration (§5) applies in bulk. Both are built by composing commands that already exist and are already tested – removing a field from a category, adding one, replacing an entity's own fields – so there is one implementation of each edit rather than two that can drift.

NEITHER DIRECTION READS OR WRITES A VALUE. Values are keyed independently of definitions, so a property whose definition moves keeps every value exactly where it was; only what the app is willing to SHOW changes. That is what makes the migration safe to offer at all. The entities that hold a non-empty value for key and would receive it if it were demoted from categoryId.

The count is what the migration's rule is stated in – 0 holders keep, exactly 1 demote, 2 or more keep – and what a confirmation prompt shows before anything moves.