@pentatonic-ai/ai-agent-sdk 0.10.0 → 0.10.2

package/packages/memory-engine-v2/extractor-sync/server.py

@@ -29,6 +29,9 @@ import time
 from contextlib import asynccontextmanager
 from typing import Any
 
+# Canonical entity-ID scheme — byte-identical copy in extractor-async (entity_id.py).
+from entity_id import entity_id, normalize_surface_form  # noqa: F401
+
 import psycopg
 import psycopg.rows
 from fastapi import FastAPI, HTTPException
@@ -114,10 +117,11 @@ def _content_hash(arena: str, content: str) -> str:
 
 
 def _entity_id(arena: str, entity_type: str, canonical_name: str) -> str:
-    """Deterministic entity ID — same canonical name in the same arena
-    always produces the same entity, so re-extractions converge."""
-    key = f"{arena}|{entity_type}|{canonical_name.lower().strip()}"
-    return "e_" + hashlib.sha256(key.encode()).hexdigest()[:24]
+    """Deterministic entity ID — same (arena, type, normalized name) always produces
+    the same entity, so re-extractions converge. Delegates to the shared `entity_id`
+    helper (entity_id.py) so extractor-sync and extractor-async key entities
+    identically — previously they did not (RFC-entity-reconciliation.md step 1)."""
+    return entity_id(arena, entity_type, canonical_name)
 
 
 def _fact_id(arena: str, category: str, subject: str | None, predicate: str | None,
@@ -212,44 +216,143 @@ def _extract_doc(req: ExtractRequest, event_id: str) -> tuple[list, list, list]:
     return entities, facts, relationships
 
 
+def _person_entity(
+    req: ExtractRequest,
+    event_id: str,
+    *,
+    name: str | None,
+    email: str | None,
+    extra_aliases: list[str] | None = None,
+) -> dict | None:
+    """Build a person entity record from a (name, email) pair, either
+    or both of which may be present. When both are present, the entity
+    is keyed by the *name* (more human-readable canonical) with the
+    email carried as an alias — so a later event that only carries the
+    email resolves to this same entity via the alias overlap check in
+    `_upsert_entities`.
+
+    See RFC §1 (extract-time pairing). The producer-agnostic shape:
+    callers extract whatever name+email pair their source carries
+    (gmail from_name/from_email, calendar displayName/email, slack
+    real_name/email, etc.) and hand it here. No producer-specific
+    knowledge in this helper.
+    """
+    name = (name or "").strip() or None
+    email = (email or "").strip() or None
+    if not name and not email:
+        return None
+
+    # Prefer name as canonical when both present. RFC §1 + §2b
+    # (accrete-only). When only email is available, fall back to email
+    # canonical — a later event carrying the pair will alias-resolve
+    # to this row and add the name as an alias, but won't rename the
+    # canonical (deferred to a follow-up; see §2b).
+    canonical = name if name else email
+    aliases_set: set[str] = set()
+    if name:
+        aliases_set.add(name)
+    if email:
+        aliases_set.add(email)
+    for a in extra_aliases or []:
+        if a:
+            aliases_set.add(a)
+
+    return {
+        "id": _entity_id(req.arena, "person", canonical),
+        "arena": req.arena,
+        "entity_type": "person",
+        "canonical_name": canonical,
+        "aliases": sorted(aliases_set),
+        "provenance_event_ids": [event_id],
+        "participant_set": req.attributes.get("participant_set", [req.arena]),
+        "disclosure_class": req.attributes.get("disclosure_class", "private"),
+    }
+
+
+# Map of metadata key prefixes → role for paired email lookup.
+# Looking up `from_email` ⟶ also look for `from_name`. Same shape for
+# `to_*`, `cc_*`, `reply_to_*`. Producer-agnostic: any producer that
+# follows the conventional `<role>_email` / `<role>_name` pattern (gmail
+# bridge, email-ingest tools, calendar producers) gets pairing for free.
+_PERSON_ROLE_PAIRS = [
+    ("from_email", "from_name"),
+    ("to_email", "to_name"),
+    ("cc_email", "cc_name"),
+    ("reply_to_email", "reply_to_name"),
+    ("sender_email", "sender_name"),
+]
+
+
 def _extract_note(req: ExtractRequest, event_id: str) -> tuple[list, list, list]:
-    """gmail / drafts: extract from + to emails, subject."""
+    """gmail / drafts / other email-shape sources: extract participants.
+
+    For each `<role>_email` in the event attributes, pair with the
+    corresponding `<role>_name` if present so the resulting entity
+    carries both surface forms (RFC §1). Falls back to email-only
+    canonical when no name is paired.
+    """
     entities, facts, relationships = [], [], []
-    for key in ("from_email", "to_email", "cc_email"):
-        val = req.attributes.get(key)
-        if isinstance(val, str) and "@" in val:
-            eid = _entity_id(req.arena, "person", val)
-            entities.append({
-                "id": eid,
-                "arena": req.arena,
-                "entity_type": "person",
-                "canonical_name": val,
-                "aliases": [val],
-                "provenance_event_ids": [event_id],
-                "participant_set": req.attributes.get("participant_set", [req.arena]),
-                "disclosure_class": req.attributes.get("disclosure_class", "private"),
-            })
+    attrs = req.attributes
+    for email_key, name_key in _PERSON_ROLE_PAIRS:
+        val = attrs.get(email_key)
+        if not isinstance(val, str) or "@" not in val:
+            continue
+        ent = _person_entity(req, event_id, name=attrs.get(name_key), email=val)
+        if ent is not None:
+            entities.append(ent)
     return entities, facts, relationships
 
 
 def _extract_event(req: ExtractRequest, event_id: str) -> tuple[list, list, list]:
-    """calendar: extract organizer + attendees as people entities."""
+    """calendar: extract organizer + attendees as people entities.
+
+    Pairs name+email when the producer carries both — modern calendar
+    producers (Google Calendar, Outlook) emit attendees as
+    `{email, displayName, responseStatus, ...}` objects. We accept
+    several common shapes (RFC §1).
+    """
     entities, facts, relationships = [], [], []
-    organizer = req.attributes.get("organizer_email")
-    attendees = req.attributes.get("attendee_emails") or []
-    for email in [organizer, *attendees]:
-        if isinstance(email, str) and "@" in email:
-            eid = _entity_id(req.arena, "person", email)
-            entities.append({
-                "id": eid,
-                "arena": req.arena,
-                "entity_type": "person",
-                "canonical_name": email,
-                "aliases": [email],
-                "provenance_event_ids": [event_id],
-                "participant_set": req.attributes.get("participant_set", [req.arena]),
-                "disclosure_class": req.attributes.get("disclosure_class", "private"),
-            })
+    attrs = req.attributes
+
+    # Organizer: may be a paired (organizer_email, organizer_name) or
+    # a structured organizer object.
+    organizer_email = attrs.get("organizer_email")
+    organizer_name = attrs.get("organizer_name") or attrs.get("organizer_display_name")
+    organizer_obj = attrs.get("organizer")
+    if isinstance(organizer_obj, dict):
+        organizer_email = organizer_email or organizer_obj.get("email")
+        organizer_name = organizer_name or organizer_obj.get("displayName") \
+            or organizer_obj.get("name")
+    ent = _person_entity(req, event_id, name=organizer_name, email=organizer_email)
+    if ent is not None:
+        entities.append(ent)
+
+    # Attendees: prefer structured objects (carry displayName), fall
+    # back to flat email list if the producer only sends emails.
+    attendees = attrs.get("attendees") or attrs.get("attendee_objects")
+    if isinstance(attendees, list):
+        for a in attendees:
+            if isinstance(a, dict):
+                ent = _person_entity(
+                    req, event_id,
+                    name=a.get("displayName") or a.get("name"),
+                    email=a.get("email"),
+                )
+                if ent is not None:
+                    entities.append(ent)
+            elif isinstance(a, str) and "@" in a:
+                ent = _person_entity(req, event_id, name=None, email=a)
+                if ent is not None:
+                    entities.append(ent)
+    else:
+        # Legacy flat-email-list path. Kept for back-compat with
+        # producers that haven't moved to structured attendee objects.
+        for email in (attrs.get("attendee_emails") or []):
+            if isinstance(email, str) and "@" in email:
+                ent = _person_entity(req, event_id, name=None, email=email)
+                if ent is not None:
+                    entities.append(ent)
+
     return entities, facts, relationships
 
 
@@ -314,31 +417,104 @@ async def _upsert_event(cur: psycopg.AsyncCursor, req: ExtractRequest,
 
 
 async def _upsert_entities(cur: psycopg.AsyncCursor, entities: list[dict]) -> None:
-    """Idempotent entity upsert: same canonical_name in same arena
-    converges to the same row. Aliases + provenance_event_ids grow
-    via array_append; never replace."""
+    """Alias-aware idempotent entity upsert.
+
+    For each entity, before inserting, look for an existing row in the
+    same (arena, entity_type) whose canonical_name OR aliases overlap
+    any of the incoming surface forms. If found, merge aliases +
+    provenance into the existing row. Otherwise insert a new row.
+
+    Concurrency safety: a Postgres advisory lock keyed on
+    `(arena, entity_type, normalised_form)` is taken for every surface
+    form before resolution, so concurrent writers (sync + async
+    extractors on the same event) serialise on the same person and
+    can't both race past the SELECT to two separate INSERTs.
+
+    Surface forms ("forms" below) = the canonical name + every alias,
+    after normalize_surface_form. The match SQL uses both the normalised
+    forms (for case-insensitive canonical_name match) and the original
+    forms (for aliases @>; aliases retain their display casing).
+
+    See RFC §2 (alias-aware resolution) and §2a (concurrency).
+    """
     for e in entities:
+        # Sort (don't `list(set(...))`) so lock acquisition order is
+        # deterministic across processes — set-iteration order depends
+        # on Python's per-process hash randomisation, so sync and
+        # async extractors processing the same person could otherwise
+        # acquire the same locks in opposite orders and deadlock.
+        forms_original = sorted({e["canonical_name"], *e.get("aliases", [])})
+        forms_normalized = sorted({normalize_surface_form(f) for f in forms_original})
+
+        # 1. Advisory lock on every form. pg_advisory_xact_lock takes a
+        # bigint; hashtext gives us one keyed on a string. Held until
+        # commit (next SELECT/UPDATE/INSERT release on txn end).
+        # Same form locked twice in the same txn is a no-op.
+        for f in forms_normalized:
+            await cur.execute(
+                "SELECT pg_advisory_xact_lock(hashtext(%s))",
+                (f"{e['arena']}|{e['entity_type']}|{f}",),
+            )
+
+        # 2. Resolve: any existing entity match any of our forms?
+        # lower(canonical_name) is what _entity_id() hashes on, so
+        # equality against forms_normalized catches the canonical
+        # match. aliases && forms_original catches alias overlap.
         await cur.execute(
             """
-            INSERT INTO entities (
-              id, arena, entity_type, canonical_name, aliases,
-              provenance_event_ids, participant_set, disclosure_class
-            ) VALUES (
-              %s, %s, %s, %s, %s, %s, %s, %s::disclosure_class
-            )
-            ON CONFLICT (id) DO UPDATE SET
-              aliases = (
-                SELECT ARRAY(SELECT DISTINCT UNNEST(entities.aliases || EXCLUDED.aliases))
-              ),
-              provenance_event_ids = (
-                SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
-              ),
-              last_seen = NOW()
+            SELECT id FROM entities
+            WHERE arena = %s
+              AND entity_type = %s
+              AND (
+                lower(canonical_name) = ANY(%s::text[])
+                OR aliases && %s::text[]
+              )
+            LIMIT 1
             """,
-            (e["id"], e["arena"], e["entity_type"], e["canonical_name"],
-             e["aliases"], e["provenance_event_ids"],
-             e["participant_set"], e["disclosure_class"]),
+            (e["arena"], e["entity_type"], forms_normalized, forms_original),
         )
+        row = await cur.fetchone()
+
+        if row is not None:
+            # 3a. Existing match — merge aliases + provenance, keep
+            # canonical as it was (accrete-only per RFC §2b).
+            existing_id = row[0]
+            await cur.execute(
+                """
+                UPDATE entities SET
+                  aliases = ARRAY(SELECT DISTINCT UNNEST(aliases || %s::text[])),
+                  provenance_event_ids = ARRAY(SELECT DISTINCT UNNEST(provenance_event_ids || %s::text[])),
+                  last_seen = NOW()
+                WHERE id = %s
+                """,
+                (e["aliases"], e["provenance_event_ids"], existing_id),
+            )
+        else:
+            # 3b. No match — insert new. ON CONFLICT (id) is a belt-
+            # and-braces fallback for the rare case where two writers
+            # collide on the same id under different surface forms;
+            # the advisory lock above is the primary defence.
+            await cur.execute(
+                """
+                INSERT INTO entities (
+                  id, arena, entity_type, canonical_name, aliases,
+                  provenance_event_ids, participant_set, disclosure_class
+                ) VALUES (
+                  %s, %s, %s, %s, %s, %s, %s, %s::disclosure_class
+                )
+                ON CONFLICT (id) DO UPDATE SET
+                  aliases = (
+                    SELECT ARRAY(SELECT DISTINCT UNNEST(entities.aliases || EXCLUDED.aliases))
+                  ),
+                  provenance_event_ids = (
+                    SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
+                  ),
+                  last_seen = NOW()
+                """,
+                (e["id"], e["arena"], e["entity_type"], e["canonical_name"],
+                 e["aliases"], e["provenance_event_ids"],
+                 e["participant_set"], e["disclosure_class"]),
+            )
 
 
 async def _enqueue_distillation(cur: psycopg.AsyncCursor, event_id: str) -> None:

package/packages/memory-engine-v2/extractor-sync/test_entity_id.py

@@ -0,0 +1,88 @@
+"""Tests for the shared entity-ID scheme (entity_id.py).
+
+Step 1 of RFC-entity-reconciliation.md: extractor-sync and extractor-async must key
+entities IDENTICALLY so the same entity converges across the deterministic and LLM
+passes. These cover the normalization contract + the id format.
+
+Run: pytest packages/memory-engine-v2/extractor-sync/test_entity_id.py
+"""
+
+from __future__ import annotations
+
+from entity_id import entity_id, normalize_surface_form
+
+
+class TestNormalizeSurfaceForm:
+    def test_lowercases(self):
+        assert normalize_surface_form("Carly Snider") == "carly snider"
+
+    def test_trims_and_collapses_internal_whitespace(self):
+        assert normalize_surface_form("  Carly   Snider  ") == "carly snider"
+
+    def test_email_case_insensitive(self):
+        assert normalize_surface_form("Carly@Pact.ORG") == "carly@pact.org"
+
+    def test_tolerates_none_and_empty(self):
+        assert normalize_surface_form(None) == ""  # type: ignore[arg-type]
+        assert normalize_surface_form("") == ""
+        assert normalize_surface_form("   ") == ""
+
+    # ---- Unicode normalisation (NFKC) ------------------------------------
+    # Without NFKC, names that render identically can have different byte
+    # sequences (precomposed vs decomposed Unicode, fullwidth vs halfwidth,
+    # ligatures vs separate glyphs) — and fragment into separate entities.
+    # These cases come up in practice with vCard imports, Mac pasteboard,
+    # IME inputs, internationalised name sources.
+
+    def test_nfkc_decomposed_to_precomposed(self):
+        # "Café" precomposed (U+00E9) vs decomposed (U+0065 + U+0301)
+        precomposed = "Café"
+        decomposed = "Café"
+        assert precomposed != decomposed  # different byte sequences
+        assert normalize_surface_form(precomposed) == normalize_surface_form(decomposed)
+
+    def test_nfkc_fullwidth_to_halfwidth_latin(self):
+        # Fullwidth Latin (often emitted by CJK-locale IMEs) collapses to
+        # halfwidth so "ＣＡＲＬＹ" keys the same as "Carly".
+        assert normalize_surface_form("ＣＡＲＬＹ") == normalize_surface_form("Carly")
+
+    def test_nfkc_ligature_to_separate_glyphs(self):
+        # Compatibility ligatures (e.g. "fi" U+FB01) decompose to "fi".
+        assert normalize_surface_form("Office") == normalize_surface_form("Office")
+
+
+class TestEntityId:
+    def test_format_is_e_prefix_plus_24_hex(self):
+        eid = entity_id("arena1", "person", "Carly Snider")
+        assert eid.startswith("e_")
+        assert len(eid) == 26  # "e_" + 24 hex
+
+    def test_casing_and_spacing_variants_converge(self):
+        a = entity_id("arena1", "person", "Carly Snider")
+        b = entity_id("arena1", "person", "carly  snider")
+        c = entity_id("arena1", "person", "  Carly Snider ")
+        assert a == b == c
+
+    def test_email_casing_converges(self):
+        a = entity_id("arena1", "person", "carly@pactcollective.org")
+        b = entity_id("arena1", "person", "Carly@PactCollective.org")
+        assert a == b
+
+    def test_distinct_people_differ(self):
+        assert entity_id("a", "person", "Ben Gordon") != entity_id("a", "person", "Ben Smith")
+
+    def test_arena_scoped(self):
+        assert entity_id("a", "person", "Carly Snider") != entity_id("b", "person", "Carly Snider")
+
+    def test_type_scoped(self):
+        # An email could be a person OR (in theory) another type; the type is part
+        # of the key, so cross-type collisions can't merge accidentally.
+        assert entity_id("a", "person", "acme.com") != entity_id("a", "org", "acme.com")
+
+    def test_email_and_name_remain_distinct_pre_resolution(self):
+        # Step 1 unifies the *scheme*, it does NOT yet merge email<->name (that is
+        # step 2's alias resolution). The email form and the name form are still
+        # different surface strings, hence different ids — by design at this stage.
+        assert entity_id("a", "person", "carly@pactcollective.org") != entity_id(
+            "a", "person", "Carly Snider"
+        )

package/packages/memory-engine-v2/extractor-sync/test_paired_extraction.py

@@ -0,0 +1,208 @@
+"""Unit tests for the step-2-onwards extractor-sync work — the
+paired-extraction helper (_person_entity) and the per-source rules
+(_extract_note, _extract_event) that drive it.
+
+Step 1 (normalize_surface_form + entity_id) is covered by
+test_entity_id.py + tests/test_entity_id_parity.py; not retested here
+to avoid drift between the two.
+
+The integration scenarios that touch the DB live in
+`packages/memory-engine-v2/tests/` and spin up a real postgres via
+testcontainers; this file is the cheap pytest layer that runs in
+unit-test CI without infra.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+
+# Load extractor-sync's server.py as a module so we can call its
+# private helpers directly.
+_THIS = Path(__file__).resolve().parent
+_SPEC = importlib.util.spec_from_file_location("extractor_sync_server",
+                                                _THIS / "server.py")
+assert _SPEC and _SPEC.loader
+sync_server = importlib.util.module_from_spec(_SPEC)
+try:
+    _SPEC.loader.exec_module(sync_server)
+except ImportError as e:
+    # If extractor-sync's runtime deps (psycopg, fastapi) aren't
+    # installed in this env, skip the whole module. The integration
+    # tests in tests/ install the full container deps.
+    pytest.skip(f"extractor-sync deps unavailable: {e}", allow_module_level=True)
+
+
+
+# ----------------------------------------------------------------------
+# _person_entity — RFC §1 paired (name, email) emission
+# ----------------------------------------------------------------------
+
+@pytest.fixture
+def stub_req():
+    """Minimal stub for ExtractRequest — only the attrs _person_entity
+    reads (arena, attributes.participant_set, .disclosure_class)."""
+    class _Req:
+        arena = "tenant:test"
+        attributes = {
+            "participant_set": ["tenant:test"],
+            "disclosure_class": "private",
+        }
+    return _Req()
+
+
+def test_person_entity_name_and_email_pair(stub_req) -> None:
+    """When both name and email present → entity keyed by NAME,
+    BOTH forms in aliases."""
+    e = sync_server._person_entity(
+        stub_req, "evt1", name="Carly Snider", email="carly@example.com"
+    )
+    assert e is not None
+    assert e["canonical_name"] == "Carly Snider"
+    assert set(e["aliases"]) == {"Carly Snider", "carly@example.com"}
+    # Id is derived from the name (not the email).
+    assert e["id"] == sync_server._entity_id("tenant:test", "person", "Carly Snider")
+
+
+def test_person_entity_email_only(stub_req) -> None:
+    """Email-only event (no name) → email-keyed entity. A later
+    paired event will alias-resolve to this via the email."""
+    e = sync_server._person_entity(stub_req, "evt1", name=None, email="x@example.com")
+    assert e is not None
+    assert e["canonical_name"] == "x@example.com"
+    assert e["aliases"] == ["x@example.com"]
+
+
+def test_person_entity_name_only(stub_req) -> None:
+    """Name-only (no email) → name-keyed entity, name as only alias."""
+    e = sync_server._person_entity(stub_req, "evt1", name="Alex Wong", email=None)
+    assert e is not None
+    assert e["canonical_name"] == "Alex Wong"
+    assert e["aliases"] == ["Alex Wong"]
+
+
+def test_person_entity_empty_returns_none(stub_req) -> None:
+    """Neither name nor email → None (caller skips)."""
+    assert sync_server._person_entity(stub_req, "evt1", name="", email=None) is None
+    assert sync_server._person_entity(stub_req, "evt1", name=None, email="") is None
+    assert sync_server._person_entity(stub_req, "evt1", name="  ", email="  ") is None
+
+
+def test_person_entity_extra_aliases_merge(stub_req) -> None:
+    """`extra_aliases` (e.g. slack id) merge with name + email in aliases."""
+    e = sync_server._person_entity(
+        stub_req, "evt1",
+        name="Sam Patel", email="sam@example.com",
+        extra_aliases=["slack:U01ABC"],
+    )
+    assert e is not None
+    assert set(e["aliases"]) == {"Sam Patel", "sam@example.com", "slack:U01ABC"}
+
+
+# ----------------------------------------------------------------------
+# _extract_note — paired emission from gmail-shape attributes
+# ----------------------------------------------------------------------
+
+def _stub_request(attributes: dict, content: str = "") -> object:
+    """Build a minimal stub of ExtractRequest for unit tests."""
+    class _Req:
+        arena = "tenant:test"
+        clientId = "client"
+        userId = "user"
+        event_type = "STORE_MEMORY"
+        source_kind = "note"
+        source_id = "src1"
+    r = _Req()
+    r.content = content
+    r.attributes = {"participant_set": ["tenant:test"],
+                    "disclosure_class": "private", **attributes}
+    return r
+
+
+def test_extract_note_pairs_name_and_email() -> None:
+    """gmail-shape: from_email + from_name → single entity name-keyed."""
+    req = _stub_request({
+        "from_email": "carly@example.com",
+        "from_name": "Carly Snider",
+    })
+    entities, _, _ = sync_server._extract_note(req, "evt1")
+    assert len(entities) == 1
+    assert entities[0]["canonical_name"] == "Carly Snider"
+    assert set(entities[0]["aliases"]) == {"Carly Snider", "carly@example.com"}
+
+
+def test_extract_note_email_only_when_no_name() -> None:
+    """gmail-shape: from_email only (no from_name) → email-keyed.
+    Same as v1 behaviour for this case (the fix is for when name
+    *is* available)."""
+    req = _stub_request({
+        "from_email": "x@example.com",
+    })
+    entities, _, _ = sync_server._extract_note(req, "evt1")
+    assert len(entities) == 1
+    assert entities[0]["canonical_name"] == "x@example.com"
+
+
+def test_extract_note_multiple_role_pairs() -> None:
+    """from_name+email + to_name+email + cc-email only → three entities."""
+    req = _stub_request({
+        "from_email": "a@example.com", "from_name": "Alice One",
+        "to_email":   "b@example.com", "to_name":   "Bob Two",
+        "cc_email":   "c@example.com",  # no cc_name
+    })
+    entities, _, _ = sync_server._extract_note(req, "evt1")
+    assert len(entities) == 3
+    canonicals = {e["canonical_name"] for e in entities}
+    assert canonicals == {"Alice One", "Bob Two", "c@example.com"}
+
+
+# ----------------------------------------------------------------------
+# _extract_event — paired emission from calendar-shape attributes
+# ----------------------------------------------------------------------
+
+def test_extract_event_structured_attendees() -> None:
+    """Modern calendar shape: attendees as {email, displayName} objects."""
+    req = _stub_request({
+        "organizer_email": "host@example.com",
+        "organizer_name": "Host Person",
+        "attendees": [
+            {"email": "a@example.com", "displayName": "Alice One"},
+            {"email": "b@example.com"},  # no displayName
+        ],
+    })
+    entities, _, _ = sync_server._extract_event(req, "evt1")
+    assert len(entities) == 3
+    by_canon = {e["canonical_name"]: e for e in entities}
+    assert "Host Person" in by_canon
+    assert "Alice One" in by_canon
+    assert "b@example.com" in by_canon
+    # Paired ones carry both forms in aliases.
+    assert "host@example.com" in by_canon["Host Person"]["aliases"]
+    assert "a@example.com" in by_canon["Alice One"]["aliases"]
+
+
+def test_extract_event_legacy_flat_attendee_emails() -> None:
+    """Back-compat: producers that only send a flat list of emails."""
+    req = _stub_request({
+        "organizer_email": "host@example.com",
+        "attendee_emails": ["a@example.com", "b@example.com"],
+    })
+    entities, _, _ = sync_server._extract_event(req, "evt1")
+    assert len(entities) == 3
+    canonicals = {e["canonical_name"] for e in entities}
+    assert canonicals == {"host@example.com", "a@example.com", "b@example.com"}
+
+
+def test_extract_event_organizer_object_form() -> None:
+    """Some calendar producers emit organizer as {email, displayName}."""
+    req = _stub_request({
+        "organizer": {"email": "x@example.com", "displayName": "X Person"},
+    })
+    entities, _, _ = sync_server._extract_event(req, "evt1")
+    assert len(entities) == 1
+    assert entities[0]["canonical_name"] == "X Person"
+    assert "x@example.com" in entities[0]["aliases"]