Lift Composition Entity
lift_composition_entityMerge two sibling descendant entities into their lowest common ancestor, resolving field conflicts and updating all three affected models in one step.
Instructions
Promote a shared-anchor entity from two sibling descendants to their lowest common ancestor. Mutates state across THREE models.
The operator has confirmed (via the composition lift-candidate view)
that the entity local_id_a on descendant_a_id and the entity
local_id_b on descendant_b_id are the same logical thing and
should be modeled once on the LCA. The route's model_id is the
operator's current context model — typically the LCA, but the server
accepts any ancestor of both descendants.
Conflict resolution. The server re-detects field-level and
attached-state conflicts against current live state before applying.
If new conflicts have surfaced since the operator's last candidate
fetch, the call returns 400 with the missing conflict keys; refresh
the lift-candidate view and resubmit with resolutions covering every
key. Each entry in field_resolutions / attached_state_resolutions
is "keep_a" | "keep_b" | "keep_both" (union for list/set
fields; falls back to B for scalars).
Over-application gate. The lift extends visibility to every descendant
of the LCA, not just the two source descendants. The server runs an
over-application gate that refuses lifts touching descendants outside
an acknowledged set; pass acknowledged_third_party_subtrees to
acknowledge specific subtrees, or skip_overapplication_gate=True to
override entirely after explicit operator confirmation.
Each affected model (LCA + both descendants) bumps version and emits a
model_refined activity event; a structured lift_applied event
with the full lift_event payload lands on the LCA. The audit pack
surfaces this under lift_history. Reverse it with
undo_composition_event(event_type="lift"), which previews unless
dry_run=False; the inverse operation is split_composition_entity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Entity kind — one of ``"assets"``, ``"attackers"``, ``"components"``. | |
| model_id | Yes | Operator's context model — the model whose composition view surfaced the candidate. Treated as a route anchor only; doesn't have to be the LCA. | |
| local_id_a | Yes | Local id of the entity on ``descendant_a_id``. | |
| local_id_b | Yes | Local id of the entity on ``descendant_b_id``. | |
| lca_model_id | Yes | Target ancestor model id (the LCA, or any ancestor higher up the chain). | |
| server_version | Yes | ||
| descendant_a_id | Yes | First source descendant model id. | |
| descendant_b_id | Yes | Second source descendant model id. | |
| field_resolutions | No | Optional per-field resolution map (e.g. ``{"description": "keep_both", "tags": "keep_a"}``). | |
| lca_descendant_ids | No | Optional snapshot of the LCA's descendant set used by the over-application gate. Omit to let the server compute it via BFS. | |
| skip_overapplication_gate | No | When True, bypass the gate after explicit operator confirmation. Default False. | |
| attached_state_resolutions | No | Optional per-state-key resolution map (e.g. ``{"state:assertions/AS3": "keep_b"}``). | |
| acknowledged_third_party_subtrees | No | Optional list of subtree roots the operator has acknowledged as in-scope for the lift. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||