fincas 0.4.1__py3-none-any.whl

crm_import/appliers/base.py

@@ -0,0 +1,363 @@
+"""What every CRM applier shares (docs/crm/phase5-importer.md 1.5, 4.5, 4.10).
+
+``run(handler, company, staged, run=..., approval_row=...)`` is the
+``unify`` apply hook for one row. Around the type's ``handler`` it:
+
+1. finds the row's job (``ImportJobBatch``) and refuses a batch of another
+   company (tenant isolation: ``unify.apply`` passes the batch's company,
+   and every target the handler loads is filtered by it);
+2. skips a record whose id **or any alias** belongs to an erased person
+   (``unify.apply`` already checks the id; aliases are checked here), and
+   scrubs the staged row as ``unify`` does;
+3. returns the earlier ``applied_ref`` when a crash left this row's writes
+   committed but its ``ApprovalRow`` unmarked (4.10: the write log names the
+   approval row);
+4. runs the handler in one savepoint inside ``suppressed()`` (no lifecycle
+   signal, no webhook: the import sends nothing, hand-off 6), with the job
+   lock taken first (``writelog.lock_job``: Job → Customer → Party → User);
+5. turns failures into the coded errors of 4.1 (``RowError``):
+   ``dependency_missing``, ``constraint``, ``conflict_stale``,
+   ``invalid_value``, ``erased``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+
+from django.contrib.contenttypes.models import ContentType
+from django.core.exceptions import ValidationError
+from django.db import IntegrityError, transaction
+from django.utils import timezone
+
+from .. import writelog
+
+DEPENDENCY_MISSING = "dependency_missing"
+CONSTRAINT = "constraint"
+CONFLICT_STALE = "conflict_stale"
+INVALID_VALUE = "invalid_value"
+ERASED = "erased"
+ERROR_CODES = (DEPENDENCY_MISSING, CONSTRAINT, CONFLICT_STALE, INVALID_VALUE, ERASED)
+
+
+class RowError(ValueError):
+    """A refused row. ``unify.apply`` stores ``str(exc)``, which starts with the code."""
+
+    coded = True  # unify.apply: store the message as is
+
+    def __init__(self, code: str, message: str):
+        if code not in ERROR_CODES:
+            raise ValueError(f"Unknown row error code {code!r}.")
+        self.code = code
+        super().__init__(f"{code}: {message}")
+
+
+@dataclass
+class Row:
+    """One approved staged row, as a handler sees it."""
+
+    company: object
+    job: object
+    staged: object
+    approval_row: object
+    session: writelog.WriteSession
+
+    @property
+    def record(self) -> dict:
+        return self.staged.raw or {}
+
+    @property
+    def data(self) -> dict:
+        return self.record.get("data") or {}
+
+    @property
+    def properties(self) -> dict:
+        return self.record.get("properties") or {}
+
+    @property
+    def mapped(self) -> dict:
+        return self.staged.mapped_values or {}
+
+    @property
+    def decision(self) -> str:
+        return self.mapped.get("decision") or ""
+
+    @property
+    def values(self) -> dict:
+        """``compare.project`` of the record, minus fields a reviewer kept."""
+        return self.mapped.get("values") or {}
+
+    @property
+    def kept(self) -> set:
+        return set(self.mapped.get("keep") or ())
+
+    @property
+    def provider(self) -> str:
+        return self.job.source.split(":", 1)[0]
+
+    @property
+    def source_tag(self) -> str:
+        """``source`` on contact points and relationships, ``marketable_source``."""
+        return f"import:{self.provider}"[:64]
+
+    @property
+    def object_type(self) -> str:
+        return self.record.get("object_type") or ""
+
+    @property
+    def source_object_type(self) -> str:
+        return self.record.get("source_object_type") or self.object_type
+
+    @property
+    def keys(self) -> list[str]:
+        """The record's source id, then its aliases."""
+        keys = [str(self.record.get("source_id"))]
+        keys += [str(a) for a in self.record.get("aliases") or [] if str(a) not in keys]
+        return keys
+
+    @cached_property
+    def mapping(self) -> dict:
+        return self.job.mapping or {}
+
+    def property_targets(self) -> dict:
+        """``{property name: target}`` from the mapping file (2.12); unnamed = sidecar."""
+        section = self.mapping.get(self.object_type) or {}
+        return dict(section.get("properties") or {})
+
+    def target(self, model):
+        """The approved ``target`` row of a link or update, from this tenant only."""
+        target = self.mapped.get("target") or {}
+        if not target.get("id"):
+            raise RowError(INVALID_VALUE, "The approved decision names no target.")
+        found = model._base_manager.filter(pk=target["id"], company_id=self.company.pk).first()
+        if found is None:
+            raise RowError(CONFLICT_STALE, f"The target {model._meta.verbose_name} is gone, or "
+                                           "belongs to another company; re-run matching.")
+        return found
+
+    # --- ExternalRefs -------------------------------------------------------
+
+    def ref_for(self, obj, source_id, *, object_type=None, metadata=None):
+        """Add the ExternalRef ``(source, object_type, source_id) -> obj``, or
+        return the one that already says so. One that names another row is a
+        ``constraint`` error (two source records cannot claim one key)."""
+        from core.models import ExternalRef
+
+        object_type = object_type or self.source_object_type
+        ct = ContentType.objects.get_for_model(type(obj))
+        existing = ExternalRef._base_manager.filter(
+            company_id=self.company.pk, source=self.job.source, object_type=object_type,
+            source_id=str(source_id),
+        ).first()
+        if existing is not None:
+            if existing.content_type_id == ct.pk and str(existing.object_id) == str(obj.pk):
+                return existing
+            raise RowError(CONSTRAINT, f"{object_type} {source_id} is already linked to another record.")
+        ref = ExternalRef.objects.create(
+            company_id=self.company.pk, source=self.job.source, object_type=object_type,
+            source_id=str(source_id), content_type=ct, object_id=obj.pk,
+            last_synced_at=timezone.now(), metadata=metadata or {},
+        )
+        return self.session.link(ref)
+
+    def refs_for(self, obj, *, metadata=None) -> None:
+        """One ExternalRef per id and alias (1.2), all to ``obj``."""
+        for key in self.keys:
+            self.ref_for(obj, key, metadata=metadata)
+
+    def resolve(self, ref: dict | None, model, *, required: bool = True):
+        """The golden row a ``*_ref`` names (``{object_type, source_id}``), by
+        ExternalRef only (1.2: never by name). Unresolved and ``required`` is
+        ``dependency_missing``, naming the ref."""
+        if not ref:
+            return None
+        found = resolve_ref(self.job, ref, model)
+        if found is None and required:
+            raise RowError(DEPENDENCY_MISSING, f"{ref.get('object_type')} {ref.get('source_id')} is not "
+                                               "imported yet (apply it, then retry this row).")
+        return found
+
+
+def source_object_types(job, object_type: str) -> list[str]:
+    """``ExternalRef.object_type`` values a canonical type was staged under in
+    ``job`` (``source_object_type``), plus the canonical name itself."""
+    from crm_import.models import ImportJobBatch
+    from unify.models import StagedRow
+
+    if len(_TYPES) > 64 and str(job.pk) not in _TYPES:
+        _TYPES.clear()  # a long-running worker: keep the memo small
+    cache = _TYPES.setdefault(str(job.pk), {})
+    if object_type not in cache:
+        batch_ids = ImportJobBatch._base_manager.filter(job_id=job.pk, object_type=object_type).values("batch_id")
+        found = set(
+            StagedRow.objects.filter(batch_id__in=batch_ids)
+            .values_list("raw__source_object_type", flat=True).distinct()
+        )
+        cache[object_type] = sorted({object_type, *(t for t in found if isinstance(t, str) and t)})
+    return cache[object_type]
+
+
+_TYPES: dict[str, dict[str, list[str]]] = {}
+
+
+def resolve_ref(job, ref: dict, model):
+    """The ``model`` row an ExternalRef of ``job``'s source names, or None."""
+    from core.models import ExternalRef
+
+    ct = ContentType.objects.get_for_model(model)
+    sid = str(ref.get("source_id") or "")
+    if not sid:
+        return None
+    hit = ExternalRef._base_manager.filter(
+        company_id=job.company_id, source=job.source, source_id=sid, content_type=ct,
+        object_type__in=source_object_types(job, ref.get("object_type") or ""),
+    ).values_list("object_id", flat=True).first()
+    if hit is None:
+        return None
+    return model._base_manager.filter(pk=hit, company_id=job.company_id).first()
+
+
+# --- the hook ---------------------------------------------------------------------
+
+
+def _erased_keys(job, record: dict) -> list[str]:
+    from core.provenance import is_erased_source
+
+    object_type = record.get("source_object_type") or record.get("object_type") or ""
+    keys = [str(record.get("source_id") or "")] + [str(a) for a in record.get("aliases") or []]
+    return [k for k in keys if k and is_erased_source(job.company_id, job.source, object_type, k)]
+
+
+#: Target types an activity (task, communication) may name a person by.
+PERSON_TARGET_TYPES = ("contact",)
+
+
+def _erased_targets(job, record: dict) -> bool:
+    """Whether a task or communication is about an erased person: one of its
+    ``target_refs`` names an erased contact. Its text is that person's (a note
+    has no participants to give it away), so it is skipped like the person."""
+    from core.provenance import is_erased_source
+
+    if record.get("object_type") not in ("task", "communication"):
+        return False
+    for ref in (record.get("data") or {}).get("target_refs") or []:
+        if not ref or ref.get("object_type") not in PERSON_TARGET_TYPES or not ref.get("source_id"):
+            continue
+        for otype in source_object_types(job, ref["object_type"]):
+            if is_erased_source(job.company_id, job.source, otype, str(ref["source_id"])):
+                return True
+    return False
+
+
+#: Types whose record names a person by an address (match.address_hashes):
+#: one under an active erasure suppression skips the whole record (3.1 step
+#: 5). A consent fact is about its address; a communication with an erased
+#: participant is that person's correspondence (staging skips it too).
+PERSON_ADDRESS_TYPES = ("contact", "owner", "consent", "communication")
+
+
+def _erased_points(job, record: dict) -> set:
+    """Address hashes of the record that carry an active erasure suppression
+    (3.1 step 5): the person may have been erased after staging, or entered by
+    hand and erased, with no ExternalRef to say so."""
+    from crm_import.match import address_hashes
+    from parties.erasure import erasure_suppression_q
+    from parties.models import Suppression
+
+    otype = record.get("object_type") or ""
+    if otype not in (*PERSON_ADDRESS_TYPES, "company"):
+        return set()
+    hashes = address_hashes(otype, record)
+    if not hashes:
+        return set()
+    return set(Suppression.objects.filter(
+        erasure_suppression_q(), company_id=job.company_id, lifted_at__isnull=True, address_hash__in=hashes,
+    ).values_list("address_hash", flat=True))
+
+
+def _scrub_erased(staged) -> None:
+    from unify.apply import ERASED_SOURCE_ERROR
+    from unify.models import StagedRow
+
+    StagedRow.objects.filter(pk=staged.pk).update(raw={"erased": True}, mapped_values={}, proposed_mapping={},
+                                                   error=ERASED_SOURCE_ERROR, updated_at=timezone.now())
+    staged.raw, staged.mapped_values, staged.proposed_mapping = {"erased": True}, {}, {}
+
+
+def _previous_ref(approval_row, record: dict) -> str | None:
+    """4.10: this row's writes committed in a run whose ``ApprovalRow`` update
+    did not. The applied record is the one the row's own ExternalRef (its
+    source id) names, whatever else the row wrote first (a team, a ref).
+
+    Looked up by the staged row, not the approval row: a crashed run may be
+    cancelled and the row applied by a new run with a new ``ApprovalRow``
+    (step 8's resume), which must not write it a second time."""
+    from core.models import ExternalRef
+    from crm_import.models import ImportWriteLog
+
+    links = ImportWriteLog._base_manager.filter(approval_row__staged_row_id=approval_row.staged_row_id,
+                                                      undone_at__isnull=True)
+    first = links.select_related("content_type").order_by("seq").first()
+    if first is None:
+        return None
+    job = first.job
+    ref = ExternalRef._base_manager.filter(
+        company_id=job.company_id, source=job.source, source_id=str(record.get("source_id")),
+        object_type=record.get("source_object_type") or record.get("object_type"),
+    ).select_related("content_type").first()
+    if ref is None:
+        return applied_ref(first.content_type.model_class(), first.object_id)
+    return applied_ref(ref.content_type.model_class(), ref.object_id)
+
+
+def applied_ref(model, pk) -> str:
+    return f"{model._meta.label_lower}:{pk}"
+
+
+def run(handler, company, staged, *, run=None, approval_row=None, **_context) -> str:
+    from core.plugins.dispatch import suppressed
+
+    if run is None or approval_row is None:
+        raise RowError(INVALID_VALUE, "CRM rows are applied through an approval run.")
+    job = writelog.job_for_batch(run.batch)
+    if job.company_id != company.pk or run.batch.company_id != company.pk:
+        raise RowError(INVALID_VALUE, "The batch belongs to another company.")
+    if approval_row.run_id != run.pk or approval_row.staged_row_id != staged.pk:
+        raise RowError(INVALID_VALUE, "The approval row is not this run's row.")
+    record = staged.raw or {}
+    erased_points = _erased_points(job, record) if not record.get("erased") else set()
+    if record.get("erased") or _erased_keys(job, record) or _erased_targets(job, record) or (
+            erased_points and record.get("object_type") in PERSON_ADDRESS_TYPES):
+        _scrub_erased(staged)
+        raise RowError(ERASED, "this source record belongs to a person whose data was erased; "
+                               "it is not imported again.")
+    if erased_points:
+        # An organisation is not the person: it only loses the erased numbers.
+        from crm_import.match import strip_erased_points
+
+        staged.raw = record = strip_erased_points(record, erased_points)
+    previous = _previous_ref(approval_row, record)
+    if previous is not None:
+        return previous
+    row = Row(company=company, job=job, staged=staged, approval_row=approval_row,
+              session=writelog.WriteSession(job, approval_row))
+    try:
+        with suppressed(), transaction.atomic():
+            writelog.lock_job(job.pk)  # first: Job → Customer → Party → User
+            ref = handler(row)
+            if record.get("object_type") == "company" and _erased_points(job, record) - erased_points:
+                raise RowError(CONFLICT_STALE, "a number of this company was erased while it was being "
+                                               "imported; retry the row.")
+            if _erased_keys(job, record) or _erased_targets(job, record) or (
+                    record.get("object_type") in PERSON_ADDRESS_TYPES and _erased_points(job, record)):
+                # Erased while this row was being written (erasure re-keys the
+                # refs under its own locks): write nothing.
+                raise RowError(ERASED, "this source record was erased while it was being imported.")
+            row.session.flush()
+    except RowError:
+        raise
+    except IntegrityError as exc:
+        raise RowError(CONSTRAINT, str(exc).splitlines()[0][:500]) from exc
+    except ValidationError as exc:
+        raise RowError(INVALID_VALUE, "; ".join(exc.messages)[:500]) from exc
+    return ref

crm_import/appliers/communications.py

@@ -0,0 +1,262 @@
+"""Notes, meetings, calls, emails → communications (docs/crm/phase5-importer.md
+2.10; hand-off sections 5 and 6).
+
+Every record goes through ``communications.ingest.record``, one call per
+row, inside the row's transaction and ``suppressed()`` (``base.run``):
+
+- ``provider`` is the job's provider and ``external_id`` the record's source
+  id, so ``record`` upserts by its own ``ExternalRef`` (``source=<provider>``,
+  ``object_type`` ``message`` / ``call`` / ``meeting``): **a re-ingest whose
+  payload hashes the same is a no-op**, and so is any re-ingest of a
+  communication erasure scrubbed. The applier also links the job's own ref
+  (``source=<provider>:<account>``, the canonical ``source_object_type``) so
+  staging recognises the record next time (``na unchanged`` / ``update``).
+- ``envelope`` is the canonical ``raw`` (``{schema_version, provider,
+  payload}``); ``known_max_version`` is the newest payload version the
+  provider's adapter writes (``raw_schema_version`` on the registered
+  ``BaseCrmExportAdapter``, else ``KNOWN_RAW_VERSIONS``, else the mapping
+  file's ``[communication] raw_schema_version``); otherwise the row fails
+  ``invalid_value``.
+- **Engagement linkage is explicit**: ``engagement=`` the associated deal's
+  engagement (``activity.targets``), else ``link_engagement=False``. The
+  hand-off's correction stands: there is no ``"explicit"`` mode.
+- ``party=`` the first associated contact or company; else ``record``'s
+  counterparty rule. ``performed_by`` is the owner. ``is_editable=False``.
+- A null ``direction`` is the mapping file's ``[communication]
+  default_direction``, else ``invalid_value`` (never guessed); a null
+  ``status`` is ``scheduled`` for a future meeting or call, else
+  ``completed``. Duration fields are dropped for kinds without
+  ``has_duration``.
+- ``last_activity_at``: ``record`` does not move it inside ``suppressed()``,
+  so the applier calls ``touch_activity`` for a completed communication of a
+  counting kind (``activity.touch_activity``, logged).
+- Participants are resolved by ``record`` against the contact points already
+  imported (contacts apply before communications, 4.2). The applier does
+  **not** run ``resolve_unlinked`` over older participants: linking them to
+  imported parties would make those parties' undo refuse. Run
+  ``manage.py resolve_participants`` once the import is accepted
+  (``docs/crm/importing.md``).
+
+**Write log.** A new communication is a ``create`` with its participants,
+raw sidecar and both refs. A re-ingest that changed snapshots the row and
+its raw first; ``record`` replaces the participants, so the old ones are
+logged as ``deleted`` (undo re-inserts them) and the new ones as creates.
+"""
+
+from __future__ import annotations
+
+from django.contrib.contenttypes.models import ContentType
+from django.utils import timezone
+
+from core.plugins.payroll import AdapterError
+
+from ..sidecar import SidecarRefused, put
+from .activity import owner_of, targets, touch_activity
+from .base import CONFLICT_STALE, INVALID_VALUE, Row, RowError, applied_ref
+from .deals import parse_instant
+
+#: Payload versions of providers whose adapter golden ships but a deployment
+#: may not enable (the export can be adapted on another machine).
+KNOWN_RAW_VERSIONS = {"hubspot": 1}
+
+
+def known_max_version(provider: str, mapping: dict | None = None) -> int:
+    """The newest raw payload version golden accepts from ``provider``: the
+    registered adapter's ``raw_schema_version``, else ``KNOWN_RAW_VERSIONS``,
+    else the mapping file's ``[communication] raw_schema_version`` (an
+    operator importing another tool's export declares it)."""
+    from core.plugins.registry import plugin_registry
+
+    try:
+        adapter = (plugin_registry.get_crm_export_adapters() or {}).get(provider)
+    except Exception:  # noqa: BLE001 — a misconfigured registry is not this row's problem
+        adapter = None
+    version = getattr(adapter, "raw_schema_version", None) if adapter is not None else None
+    version = version or KNOWN_RAW_VERSIONS.get(provider) or ((mapping or {}).get("communication") or {}).get(
+        "raw_schema_version")
+    if isinstance(version, bool) or not isinstance(version, int) or version < 1:
+        raise RowError(INVALID_VALUE, f"golden does not know which raw payload versions the {provider!r} adapter "
+                                      "writes: enable its plugin, or set [communication] raw_schema_version in the "
+                                      "mapping file.")
+    return version
+
+
+def _direction(row: Row, kind_entry) -> str:
+    direction = row.data.get("direction") or ((row.mapping.get("communication") or {}).get("default_direction"))
+    if direction is None and len(kind_entry.directions) == 1:
+        direction = kind_entry.directions[0]  # a note is internal
+    if direction not in kind_entry.directions:
+        raise RowError(INVALID_VALUE, f"a {kind_entry.name} is {', '.join(kind_entry.directions)}, not "
+                                      f"{direction!r}; set [communication] default_direction in the mapping file "
+                                      "to import records without one.")
+    return direction
+
+
+def _status(row: Row, occurred_at) -> str:
+    from communications.models import Communication
+
+    status = row.data.get("status")
+    if status is None:
+        future = occurred_at > timezone.now()
+        return Communication.Status.SCHEDULED if future else Communication.Status.COMPLETED
+    if status not in Communication.Status.values:
+        raise RowError(INVALID_VALUE, f"communication status {status!r} is not one of "
+                                      f"{', '.join(Communication.Status.values)}.")
+    return status
+
+
+def _existing(row: Row, provider: str, external_id: str):
+    from communications.models import Communication
+    from core.models import ExternalRef
+
+    hit = ExternalRef._base_manager.filter(
+        company_id=row.company.pk, source=provider, source_id=external_id,
+        content_type=ContentType.objects.get_for_model(Communication),
+    ).values_list("object_id", flat=True).first()
+    if hit is None:
+        return None
+    return Communication._base_manager.filter(pk=hit, company_id=row.company.pk).first()
+
+
+def _targets(row: Row) -> dict:
+    """The mapping file's property targets: its tables are the provider's
+    (``[note.properties]``, ``[call.properties]``, …), so by the record's
+    ``source_object_type``."""
+    section = row.mapping.get(row.source_object_type) or {}
+    return dict(section.get("properties") or {}) if isinstance(section, dict) else {}
+
+
+def _lock_parties(row: Row, linked, existing) -> None:
+    """Lock every party the row will point at (the targets, the participants
+    ``record`` will resolve, the existing row's party) right after the job
+    lock and before ``record`` locks the communication: Job → Party, the order
+    erasure takes too."""
+    from communications.participants import match, normalize_address
+    from core.identity.resolve import lock_login_rows
+
+    ids = {getattr(linked.party, "pk", None), getattr(linked.engagement, "party_id", None),
+           getattr(existing, "party_id", None)}
+    for p in row.data.get("participants") or []:
+        channel, normalized = normalize_address(p.get("address") or "")
+        if normalized:
+            ids.add(match(row.company.pk, channel, normalized)[0])
+    ids.discard(None)
+    if ids:
+        lock_login_rows(parties=sorted(ids, key=str))
+
+
+def _participants(row: Row) -> list[dict]:
+    out = []
+    for p in row.data.get("participants") or []:
+        out.append({"role": p.get("role"), "address": p.get("address") or "", "display_name": p.get("name") or ""})
+    return out
+
+
+def apply(row: Row) -> str:
+    from communications import ingest
+    from communications.kinds import get_kind
+    from communications.models import Communication, CommunicationParticipant, CommunicationRaw
+    from core.models import ExternalRef
+
+    from .. import writelog
+
+    if row.decision not in ("create", "update"):
+        raise RowError(INVALID_VALUE, f"a communication row cannot be applied as {row.decision!r}.")
+    data = row.data
+    kind = data.get("kind")
+    entry = get_kind(kind)
+    if entry is None:
+        raise RowError(INVALID_VALUE, f"communication kind {kind!r} is not registered "
+                                      "(GOLDEN_COMMUNICATION_KINDS).")
+    occurred_at = parse_instant(data.get("occurred_at"))
+    if occurred_at is None:
+        raise RowError(INVALID_VALUE, "occurred_at is not a UTC instant.")
+    ended_at = parse_instant(data.get("ended_at")) if entry.has_duration else None
+    if ended_at is not None and ended_at < occurred_at:
+        ended_at = None
+    provider = row.provider
+    external_id = str(row.record.get("source_id"))
+    owner, owner_flags = owner_of(row)
+    linked = targets(row)
+    existing = _existing(row, provider, external_id)
+    _lock_parties(row, linked, existing)
+    old_parts, raw = {}, None
+    direction, status = _direction(row, entry), _status(row, occurred_at)
+    if existing is not None:
+        # Snapshot what record() may change before it runs: the row, its raw, its participants.
+        row.session.touch(Communication, existing.pk)
+        raw = CommunicationRaw._base_manager.filter(communication=existing).first()
+        if raw is not None:
+            row.session.touch(CommunicationRaw, raw.pk)
+        old_parts = {p.pk: writelog.snapshot(CommunicationParticipant, p.pk)
+                     for p in CommunicationParticipant._base_manager.filter(communication=existing)}
+        for ref_pk in ExternalRef._base_manager.filter(
+                company_id=row.company.pk, source=provider, source_id=external_id,
+                content_type=ContentType.objects.get_for_model(Communication)).values_list("pk", flat=True):
+            row.session.touch(ExternalRef, ref_pk)  # record() bumps its last_synced_at
+    try:
+        result = ingest.record(
+            row.company, kind, direction=direction, occurred_at=occurred_at,
+            participants=_participants(row), provider=provider, external_id=external_id,
+            envelope=data.get("raw"), known_max_version=known_max_version(provider, row.mapping),
+            subject=data.get("subject") or "", body_text=data.get("body_text") or "",
+            summary=data.get("summary") or "", status=status, ended_at=ended_at,
+            duration_seconds=data.get("duration_seconds") if entry.has_duration else None,
+            engagement=linked.engagement, party=linked.party, performed_by=owner,
+            metadata=dict(existing.metadata or {}) if existing is not None else {},
+            is_editable=False, link_engagement=False,
+        )
+    except (ingest.IngestError, AdapterError, ValueError) as exc:
+        if isinstance(exc, RowError):
+            raise
+        raise RowError(INVALID_VALUE, str(exc)[:500]) from exc
+    comm = result.communication
+    if existing is None and not result.created:
+        # record() lost a race for its ref to a concurrent first import and
+        # rewrote that row: nothing here snapshotted it, so write nothing.
+        raise RowError(CONFLICT_STALE, "this communication was imported concurrently; retry the row.")
+    scrubbed = CommunicationRaw._base_manager.filter(communication=comm, payload=ingest.ERASED_PAYLOAD).exists()
+    if result.created:
+        row.session.create(comm)
+        for part in CommunicationParticipant._base_manager.filter(communication=comm):
+            row.session.create(part)
+        raw = CommunicationRaw._base_manager.filter(communication=comm).first()
+        if raw is not None:
+            row.session.create(raw)
+        ref = ExternalRef._base_manager.get(company_id=row.company.pk, source=provider,
+                                            object_type=ingest.object_type_for(kind), source_id=external_id)
+        row.session.link(ref)
+    elif result.changed:
+        for pk, before in old_parts.items():
+            row.session.deleted(CommunicationParticipant, pk, before)
+        for part in CommunicationParticipant._base_manager.filter(communication=comm):
+            row.session.create(part)
+        if raw is None:
+            raw = CommunicationRaw._base_manager.filter(communication=comm).first()
+            if raw is not None:
+                row.session.create(raw)
+    elif not scrubbed:
+        # The payload hashes the same, but what lives outside it (the
+        # associations, the owner, a mapped direction) may not: an approved
+        # update applies those columns, logged (``touch`` above).
+        fixes = {"engagement_id": getattr(linked.engagement, "pk", None),
+                 "performed_by_id": getattr(owner, "pk", None), "direction": direction, "status": status}
+        if linked.party is not None:
+            fixes["party_id"] = linked.party.pk
+        fixes = {k: v for k, v in fixes.items() if getattr(comm, k) != v}
+        if fixes:
+            row.session.update(comm, **fixes)
+    if not scrubbed and (result.changed or row.decision == "update"):
+        if comm.engagement_id and comm.status == Communication.Status.COMPLETED and entry.counts_as_activity:
+            touch_activity(row, comm.engagement_id, comm.occurred_at)
+        values = {n: v for n, v in row.properties.items() if _targets(row).get(n, "sidecar") == "sidecar"}
+        # body_html stays in the raw payload (CommunicationRaw, view_raw_communication), not here.
+        derived = {"import_flags": owner_flags, "import_unresolved_targets": linked.unresolved,
+                   "import_other_targets": linked.others}
+        try:
+            put(comm, provider, values, derived={k: v for k, v in derived.items() if v}, session=row.session)
+        except SidecarRefused as exc:
+            raise RowError(INVALID_VALUE, str(exc)) from exc
+    if not scrubbed:  # erasure scrubbed it: add nothing that points at it
+        row.refs_for(comm)
+    return applied_ref(Communication, comm.pk)