Update Deal

Update a deal (partial update).

Contact operations run in a fixed order within the single transaction: remove_contact_ids -> add_contact_ids -> contact_roles. That order is what makes the useful combinations work:

• a contact linked by add_contact_ids in THIS request can be given a role by contact_roles in the same call (roles run last);
• an id in both remove_contact_ids and add_contact_ids ends up linked (add runs after remove), so a role for it still applies;
• an id in remove_contact_ids and contact_roles but NOT in add_contact_ids is unlinked by the time roles run, so it is a 422 naming that id rather than a role written to a row that no longer exists.

A contact_roles entry for a contact that is neither already linked nor being added is a 422; the whole transaction rolls back, so a partially applied batch is not a state this endpoint can produce.

background_tasks carries the deal.stage_changed fan-out only. It is injected, not a body field, so it does not appear in the OpenAPI schema and the request contract is unchanged (pinned by developer_api/tests/test_deal_stage_events.py). Publishing there rather than inline keeps the Redis round trip off the caller's latency budget and makes "strictly after the commit" structural: the task is queued only after the session context has exited, and FastAPI attaches background tasks to the SUCCESS response, so a raise anywhere above publishes nothing.