@pentatonic-ai/ai-agent-sdk 0.10.15 → 0.10.16

package/dist/index.cjs

@@ -878,7 +878,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.15";
+var VERSION = "0.10.16";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/dist/index.js

@@ -847,7 +847,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.15";
+var VERSION = "0.10.16";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.10.15",
+  "version": "0.10.16",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory-engine-v2/compat/server.py

@@ -928,7 +928,7 @@ async def list_entities(req: GraphQueryRequest):
         params.extend([pattern, pattern])
     sql = f"""
         SELECT id, arena, entity_type, canonical_name, aliases,
-               provenance_event_ids, last_seen
+               provenance_event_ids, attributes, last_seen
           FROM entities
          WHERE {' AND '.join(conditions)}
       ORDER BY last_seen DESC

package/packages/memory-engine-v2/extractor-async/entity_id.py

@@ -55,3 +55,23 @@ def entity_id(arena: str, entity_type: str, canonical_name: str) -> str:
     """
     key = f"{arena}|{entity_type}|{normalize_surface_form(canonical_name)}"
     return "e_" + hashlib.sha256(key.encode()).hexdigest()[:24]
+
+
+def person_id_key(name: str | None, email: str | None) -> str:
+    """The string `entity_id()` should hash to mint a PERSON's node id — the
+    EMAIL (the person's deterministic hard key) when present, else the name.
+
+    Lives HERE, in the byte-identical shared file, BECAUSE both extractors mint
+    person nodes and must agree: the sync pass builds them from the envelope at
+    ingest (it has the email), the async pass builds them from prose (email
+    promoted to an alias). Keying both on the email means the same person mints
+    the SAME id from either pass and in any processing order — converging to one
+    node instead of sync's name-keyed node and async's node racing, or a
+    re-distill re-homing them differently. The name is the fallback for a person
+    with no email (Fusion still merges those fuzzily). `entity_id()` normalises
+    (lowercase + trim) the result, so casing/whitespace variants of an email
+    collapse. (Org keying is the async-only `org_node_id_key`; person keying is
+    cross-pass, so it belongs in this parity-guarded file.)
+    """
+    e = (email or "").strip()
+    return e if e else (name or "")

package/packages/memory-engine-v2/extractor-async/test_fact_source.py

@@ -0,0 +1,62 @@
+"""Tests for fact_source — deriving the source label stamped onto facts.
+
+The contract under test (SoR-drift foundation): prefer the finer
+producer label `attributes.source` (gmail / hubspot / ...) over the
+coarse `source_kind` enum; fall back to `source_kind` when no finer
+label; return None only when neither is present (NULL == source-unknown,
+the pre-009 state). Pure + total: never raises.
+
+Run: pytest packages/memory-engine-v2/extractor-async/test_fact_source.py
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from worker import fact_source
+
+
+class TestFactSource:
+    def test_prefers_finer_attributes_source(self):
+        # attributes.source (hubspot) wins over the coarse source_kind
+        # (system) — this is the CRM-vs-email granularity SoR-drift needs.
+        ev = {"source_kind": "system", "attributes": {"source": "hubspot"}}
+        assert fact_source(ev) == "hubspot"
+
+    def test_email_finer_than_note_kind(self):
+        ev = {"source_kind": "note", "attributes": {"source": "gmail"}}
+        assert fact_source(ev) == "gmail"
+
+    def test_falls_back_to_source_kind_when_no_attribute(self):
+        ev = {"source_kind": "chat", "attributes": {}}
+        assert fact_source(ev) == "chat"
+
+    def test_falls_back_when_attributes_missing(self):
+        ev = {"source_kind": "doc"}
+        assert fact_source(ev) == "doc"
+
+    def test_strips_whitespace(self):
+        ev = {"source_kind": "system", "attributes": {"source": "  slack  "}}
+        assert fact_source(ev) == "slack"
+
+    def test_blank_attribute_falls_through_to_kind(self):
+        # An empty/whitespace `source` must NOT win over a real kind.
+        ev = {"source_kind": "doc", "attributes": {"source": "   "}}
+        assert fact_source(ev) == "doc"
+
+    # --- None cases: source-unknown, column stays NULL ---
+
+    @pytest.mark.parametrize(
+        "ev",
+        [
+            {},
+            {"attributes": {}},
+            {"attributes": {"source": ""}},
+            {"source_kind": "", "attributes": {"source": None}},
+            {"source_kind": None, "attributes": None},
+            # Non-string types must not crash and must not be stamped.
+            {"source_kind": 7, "attributes": {"source": 42}},
+        ],
+    )
+    def test_returns_none_when_no_usable_source(self, ev):
+        assert fact_source(ev) is None

package/packages/memory-engine-v2/extractor-async/test_org_domain.py

@@ -0,0 +1,329 @@
+"""Org-domain hard-key stamping — the deterministic helpers that turn an
+event's structured email envelope into an org's domain hard key
+(entity-ontology-the-spine.md §IV; registry §B).
+
+Pure-logic tests only (no DB) — they exercise the precision guard that makes
+envelope-derived stamping safe (`match_org_domain`) plus envelope parsing
+(`event_org_domains`) and label extraction (`domain_label`). The upsert SQL that
+consumes them is covered by the engine image build+import check in CI."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+_THIS = Path(__file__).resolve().parent
+_SPEC = importlib.util.spec_from_file_location("extractor_async_worker",
+                                               _THIS / "worker.py")
+assert _SPEC and _SPEC.loader
+worker = importlib.util.module_from_spec(_SPEC)
+try:
+    _SPEC.loader.exec_module(worker)
+except ImportError as e:
+    pytest.skip(f"extractor-async deps unavailable: {e}", allow_module_level=True)
+
+
+# ----------------------------------------------------------------------
+# _domain_of — pull the domain out of an email-ish string
+# ----------------------------------------------------------------------
+
+def test_domain_of_plain_email() -> None:
+    assert worker._domain_of("bob@lego.com") == "lego.com"
+
+
+def test_domain_of_display_name_form() -> None:
+    assert worker._domain_of("Bob Smith <bob@LEGO.com>") == "lego.com"
+
+
+def test_domain_of_subdomain_preserved() -> None:
+    # domain_label, not _domain_of, reduces to the registrable label.
+    assert worker._domain_of("a@mail.acme.co.uk") == "mail.acme.co.uk"
+
+
+def test_domain_of_non_email_is_none() -> None:
+    assert worker._domain_of("Bob Smith") is None
+    assert worker._domain_of("") is None
+
+
+# ----------------------------------------------------------------------
+# domain_label — registrable label
+# ----------------------------------------------------------------------
+
+def test_domain_label_simple() -> None:
+    assert worker.domain_label("lego.com") == "lego"
+
+
+def test_domain_label_multi_part_tld() -> None:
+    assert worker.domain_label("boots.co.uk") == "boots"
+
+
+def test_domain_label_subdomain() -> None:
+    assert worker.domain_label("mail.acme.com") == "acme"
+
+
+def test_domain_label_subdomain_multi_part_tld() -> None:
+    assert worker.domain_label("careers.boots.co.uk") == "boots"
+
+
+def test_domain_label_degenerate() -> None:
+    assert worker.domain_label("localhost") is None
+    assert worker.domain_label("") is None
+
+
+# ----------------------------------------------------------------------
+# event_org_domains — corporate domains from the structured envelope
+# ----------------------------------------------------------------------
+
+def test_event_domains_from_contact_email() -> None:
+    assert worker.event_org_domains({"contact_email": "ceo@lego.com"}) == {"lego.com"}
+
+
+def test_event_domains_recipient_list_string() -> None:
+    attrs = {"to_emails": "a@acme.com, b@acme.com; c@globex.com"}
+    assert worker.event_org_domains(attrs) == {"acme.com", "globex.com"}
+
+
+def test_event_domains_recipient_list_array() -> None:
+    attrs = {"cc_emails": ["a@acme.com", "b@globex.com"]}
+    assert worker.event_org_domains(attrs) == {"acme.com", "globex.com"}
+
+
+def test_event_domains_drops_freemail() -> None:
+    attrs = {"contact_email": "someone@gmail.com", "to_emails": "boss@acme.com"}
+    assert worker.event_org_domains(attrs) == {"acme.com"}
+
+
+def test_event_domains_drops_tenant_domain() -> None:
+    # Our own people are not an external org.
+    attrs = {"to_emails": "phil@pentatonic.com, ext@acme.com"}
+    assert worker.event_org_domains(attrs) == {"acme.com"}
+
+
+def test_event_domains_author_only_if_email() -> None:
+    # `author` is often a name/user-id, not an email — only count it when it is one.
+    assert worker.event_org_domains({"author": "Phil Hauser"}) == set()
+    assert worker.event_org_domains({"author": "phil@acme.com"}) == {"acme.com"}
+
+
+def test_event_domains_empty_inputs() -> None:
+    assert worker.event_org_domains(None) == set()
+    assert worker.event_org_domains({}) == set()
+
+
+# ----------------------------------------------------------------------
+# event_org_domains — direct SoR domain attribute (no email envelope)
+# ----------------------------------------------------------------------
+
+def test_event_domains_from_direct_domain_attr() -> None:
+    # A CRM company record carries the org's domain directly (no envelope email).
+    assert worker.event_org_domains(
+        {"domain": "Acme.com", "hubspot_kind": "company"}
+    ) == {"acme.com"}
+    assert worker.event_org_domains({"company_domain": "acme.com"}) == {"acme.com"}
+    assert worker.event_org_domains({"org_domain": "acme.com"}) == {"acme.com"}
+
+
+def test_event_domains_domain_attr_normalises_url_and_www() -> None:
+    assert worker.event_org_domains(
+        {"domain": "https://www.acme.com/about?x=1"}
+    ) == {"acme.com"}
+
+
+def test_event_domains_domain_attr_drops_freemail_and_tenant() -> None:
+    assert worker.event_org_domains({"domain": "gmail.com"}) == set()
+    assert worker.event_org_domains({"company_domain": "pentatonic.com"}) == set()
+
+
+def test_event_domains_domain_attr_rejects_non_domains() -> None:
+    assert worker.event_org_domains({"domain": "not a domain"}) == set()
+    assert worker.event_org_domains({"domain": "bob@acme.com"}) == set()
+    assert worker.event_org_domains({"domain": "localhost"}) == set()
+
+
+def test_event_domains_merges_envelope_and_direct_attr() -> None:
+    assert worker.event_org_domains(
+        {"contact_email": "a@globex.com", "domain": "acme.com"}
+    ) == {"globex.com", "acme.com"}
+
+
+# ----------------------------------------------------------------------
+# match_org_domain — the precision guard
+# ----------------------------------------------------------------------
+
+def test_match_exact_name_to_domain() -> None:
+    assert worker.match_org_domain("LEGO", {"lego.com"}) == "lego.com"
+
+
+def test_match_name_with_suffix_word() -> None:
+    # "LEGO Group" → token "lego" matches lego.com.
+    assert worker.match_org_domain("LEGO Group", {"lego.com"}) == "lego.com"
+
+
+def test_match_squished_name_equals_label() -> None:
+    # de-spaced name "legogroup" EQUALS the domain label "legogroup"
+    # (whole-name match, not a prefix).
+    assert worker.match_org_domain("Lego Group", {"legogroup.com"}) == "legogroup.com"
+
+
+def test_no_match_when_domain_is_a_bystander() -> None:
+    # THE key safety case: an email FROM acme.com that merely *mentions* Globex
+    # must not stamp acme.com onto Globex.
+    assert worker.match_org_domain("Globex", {"acme.com"}) is None
+
+
+# Prefix-match false positives — the reason the original `squished.startswith`
+# clause was removed. One org's name starting with another org's label must NOT
+# stamp that other org's domain (a mis-merge at ingest, via the alias-overlap
+# path, that isn't behind the Fusion Drive's dry-run/audit gate).
+def test_no_match_name_starts_with_other_org_label() -> None:
+    # "applebees".startswith("apple") — must NOT stamp apple.com onto Applebee's.
+    assert worker.match_org_domain("Applebee's", {"apple.com"}) is None
+    # "legoland".startswith("lego") — must NOT stamp lego.com onto Legoland.
+    assert worker.match_org_domain("Legoland", {"lego.com"}) is None
+    # "microsoft".startswith("micro") — must NOT stamp micro.com onto Microsoft.
+    assert worker.match_org_domain("Microsoft", {"micro.com"}) is None
+
+
+def test_match_still_holds_for_legit_token_and_whole_name() -> None:
+    # the cases the prefix clause was *meant* for are covered without it:
+    assert worker.match_org_domain("LEGO Group", {"lego.com"}) == "lego.com"   # token
+    assert worker.match_org_domain("Microsoft", {"microsoft.com"}) == "microsoft.com"  # whole name
+    assert worker.match_org_domain("Salesforce", {"salesforce.com"}) == "salesforce.com"  # whole name
+
+
+def test_match_picks_the_right_domain_among_several() -> None:
+    domains = {"acme.com", "lego.com", "globex.com"}
+    assert worker.match_org_domain("LEGO", domains) == "lego.com"
+
+
+def test_no_match_on_short_label_substring() -> None:
+    # short labels (<4) must match a token exactly, never as a substring —
+    # avoids "hp" matching "championship" etc.
+    assert worker.match_org_domain("Championship Org", {"hp.com"}) is None
+
+
+def test_match_short_label_exact_token() -> None:
+    # but a genuine short-name org still matches its own domain as a token.
+    assert worker.match_org_domain("HP", {"hp.com"}) == "hp.com"
+
+
+def test_ambiguous_two_matching_domains_is_none() -> None:
+    # genuine ambiguity → defer to fusion, don't guess.
+    assert worker.match_org_domain("Acme", {"acme.com", "acme.co.uk"}) is None
+
+
+def test_no_match_empty() -> None:
+    assert worker.match_org_domain("", {"lego.com"}) is None
+    assert worker.match_org_domain("LEGO", set()) is None
+
+
+# ----------------------------------------------------------------------
+# org_node_id_key — the string entity_id() hashes for the node (task #2)
+# ----------------------------------------------------------------------
+
+def test_id_key_is_the_domain_for_a_stamped_org() -> None:
+    # The whole point: name variants don't matter — the id keys on the domain.
+    assert worker.org_node_id_key("org", "LEGO Group", "lego.com") == "lego.com"
+    assert worker.org_node_id_key("org", "LEGO", "lego.com") == "lego.com"
+
+
+def test_id_key_falls_back_to_name_without_a_domain() -> None:
+    assert worker.org_node_id_key("org", "Some Prose Org", None) == "Some Prose Org"
+
+
+def test_id_key_never_touches_non_orgs() -> None:
+    # A person carries an email hard key, but person id-keying is a separate
+    # follow-up — this helper must leave non-orgs on their name.
+    assert worker.org_node_id_key("person", "Johann", "pentatonic.com") == "Johann"
+    assert worker.org_node_id_key("product", "Widget", "widget.com") == "Widget"
+
+
+def test_id_key_drives_a_domain_keyed_entity_id() -> None:
+    # End-to-end: two LEGO name-variants with the same domain mint the SAME id.
+    a = worker.entity_id(
+        "arena1", "org", worker.org_node_id_key("org", "LEGO Group", "lego.com")
+    )
+    b = worker.entity_id(
+        "arena1", "org", worker.org_node_id_key("org", "LEGO", "lego.com")
+    )
+    assert a == b
+    # …and it differs from the old name-keyed id (so a re-distill re-homes them).
+    name_keyed = worker.entity_id("arena1", "org", "LEGO Group")
+    assert a != name_keyed
+
+
+# ----------------------------------------------------------------------
+# person_id_key — email hard key, shared with the sync pass (task #2)
+# ----------------------------------------------------------------------
+
+def test_person_id_key_prefers_email() -> None:
+    assert worker.person_id_key("Johann", "johann@p.com") == "johann@p.com"
+    assert worker.person_id_key("Johann", None) == "Johann"
+    assert worker.person_id_key(None, None) == ""
+
+
+def test_person_id_key_drives_an_email_keyed_entity_id() -> None:
+    # Two name-variants of one person, same email → identical node id, distinct
+    # from the name-keyed one (so sync + async + a re-distill all converge).
+    a = worker.entity_id(
+        "arena1", "person", worker.person_id_key("Johann Boedecker", "j@p.com")
+    )
+    b = worker.entity_id(
+        "arena1", "person", worker.person_id_key("BOEDECKER, JOHANN", "J@P.com")
+    )
+    assert a == b
+    assert a != worker.entity_id("arena1", "person", "Johann Boedecker")
+
+
+# ----------------------------------------------------------------------
+# event_record_subject — SoR external-id fallback (registry A.1 step 5)
+# ----------------------------------------------------------------------
+
+def test_record_subject_company_is_org() -> None:
+    assert worker.event_record_subject(
+        {"source_id": "hubspot:company:12345", "hubspot_kind": "company"}
+    ) == ("org", "hubspot:company:12345")
+
+
+def test_record_subject_contact_is_person() -> None:
+    assert worker.event_record_subject(
+        {"source_id": "hubspot:contact:777", "hubspot_kind": "contact"}
+    ) == ("person", "hubspot:contact:777")
+
+
+def test_record_subject_deal_is_not_a_core_entity() -> None:
+    # deal/ticket/custom types aren't core graph entities → no external-id key.
+    assert worker.event_record_subject(
+        {"source_id": "hubspot:deal:9", "hubspot_kind": "deal"}
+    ) == (None, None)
+
+
+def test_record_subject_requires_a_source_id() -> None:
+    assert worker.event_record_subject({"hubspot_kind": "company"}) == (None, None)
+    assert worker.event_record_subject({"source_id": "  ", "hubspot_kind": "company"}) == (
+        None,
+        None,
+    )
+
+
+def test_record_subject_plain_comms_event_is_none() -> None:
+    # An ordinary email/slack event is not a single record.
+    assert worker.event_record_subject({"contact_email": "a@acme.com"}) == (None, None)
+    assert worker.event_record_subject(None) == (None, None)
+    assert worker.event_record_subject({}) == (None, None)
+
+
+def test_external_id_keys_a_domainless_record_node() -> None:
+    # The fallback: a company record with no resolvable domain keys on its
+    # external id, so two imports of the same record converge to one node.
+    ext = "hubspot:company:12345"
+    assert worker.entity_id("arena1", "org", ext) == worker.entity_id(
+        "arena1", "org", ext
+    )
+    # …and that's distinct from the name-keyed node it replaces.
+    assert worker.entity_id("arena1", "org", ext) != worker.entity_id(
+        "arena1", "org", "Acme Corp"
+    )

package/packages/memory-engine-v2/extractor-async/worker.py

@@ -41,7 +41,7 @@ import psycopg
 import psycopg.rows
 
 from confidence import born_salience, corroborated_confidence
-from entity_id import entity_id, normalize_surface_form
+from entity_id import entity_id, normalize_surface_form, person_id_key
 from source_time import event_source_time, parse_source_time
 from extraction_schema import (
     ALLOWED_ENT_TYPES,
@@ -801,6 +801,217 @@ def _digit_ratio(s: str) -> float:
     return sum(c.isdigit() for c in stripped) / len(stripped)
 
 
+# ----------------------------------------------------------------------
+# Org-domain hard-key stamping (entity-ontology-the-spine §IV / registry §B)
+#
+# An organization's email DOMAIN is its deterministic hard key — the join that
+# unifies the same org seen across sources and kills name-fragmentation (the
+# LEGO-×12 / Johann-×5 problem). The async LLM pass mints org entities by NAME
+# from prose; the DOMAIN lives in the event's structured envelope (contact_email
+# / to_emails / cc_emails / author). The structured-data-graph audit found Seesa
+# *emits* this bag but the graph *drops* it. Here we bring the two together:
+# derive corporate domains from the envelope, and — only when a domain's
+# registrable label matches the org's name — stamp it onto that org as a
+# resolution alias (so domain-sharing orgs merge via the existing alias-overlap
+# path) and as an `attributes.domain` hard key on the node.
+#
+# Forward-only: new events get stamped; a re-distill backfills history. Org-only
+# — the sync pass never mints orgs (it emits person/document from the envelope),
+# so this lives entirely in the async worker and leaves entity-id parity intact.
+# ----------------------------------------------------------------------
+
+# Consumer / free email providers — a shared domain here means "both use Gmail",
+# NOT "same org", so an org must never be keyed on these.
+FREEMAIL_DOMAINS = frozenset({
+    "gmail.com", "googlemail.com", "outlook.com", "hotmail.com", "live.com",
+    "msn.com", "yahoo.com", "yahoo.co.uk", "ymail.com", "icloud.com", "me.com",
+    "mac.com", "aol.com", "proton.me", "protonmail.com", "gmx.com", "gmx.net",
+    "mail.com", "zoho.com", "yandex.com", "fastmail.com", "qq.com", "163.com",
+    "126.com",
+})
+
+# The tenant's own domain(s) — our people, not an external org; never key an org
+# on our domain (it would collapse unrelated externals under us). Comma-list via
+# env; defaults to the known tenant.
+TENANT_EMAIL_DOMAINS = frozenset(
+    d.strip().lower()
+    for d in os.environ.get("TENANT_EMAIL_DOMAINS", "pentatonic.com").split(",")
+    if d.strip()
+)
+
+# Multi-label public suffixes we actually see — enough to pull the registrable
+# label ("boots" from boots.co.uk) without a full public-suffix-list dependency.
+_MULTI_LABEL_TLDS = frozenset({
+    "co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "co.jp", "com.au", "net.au",
+    "org.au", "co.nz", "com.br", "co.in", "com.cn", "co.za", "com.sg", "com.hk",
+})
+
+_EMAIL_DOMAIN_RE = re.compile(r"[\w.+-]+@([a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9-]+)+)", re.I)
+
+
+def _domain_of(value: str) -> str | None:
+    """Lowercased domain of an email address found in ``value``, else None."""
+    if not value or "@" not in value:
+        return None
+    m = _EMAIL_DOMAIN_RE.search(value)
+    return m.group(1).lower() if m else None
+
+
+def _bare_domain(value: str) -> str | None:
+    """Normalise a structured domain field to a bare host — 'acme.com' from
+    'Acme.com', 'https://www.acme.com/about', etc. Used for system-of-record
+    records (e.g. a CRM company) that carry the org's domain DIRECTLY, not via an
+    email envelope. None when it isn't a plausible domain (no dot, has a space,
+    or looks like an email — those go through `_domain_of`)."""
+    if not isinstance(value, str):
+        return None
+    d = value.strip().lower()
+    if not d:
+        return None
+    d = d.split("//")[-1].split("/")[0].split("?")[0]  # strip scheme + path
+    if d.startswith("www."):
+        d = d[4:]
+    if "." not in d or " " in d or "@" in d:
+        return None
+    return d
+
+
+def event_org_domains(attrs: dict[str, Any] | None) -> set[str]:
+    """Corporate domains in an event's structured data — the deterministic
+    source of org hard keys. Two structured sources:
+      - the participant ENVELOPE: ``contact_email``/``from_email``/``author`` and
+        the recipient lists ``to_emails``/``cc_emails`` (list or delimited
+        string), domain taken from each address;
+      - a system-of-record's DIRECT domain field (``domain``/``company_domain``/
+        ``org_domain``) — e.g. a CRM company record carries the org's domain even
+        though there's no email envelope (it would otherwise only sit in prose).
+    Drops freemail + the tenant's own domain. Empty set on missing/garbage input
+    — never raises (this runs in the hot upsert path)."""
+    if not attrs:
+        return set()
+    domains: set[str] = set()
+    raw: list[str] = []
+    for key in ("contact_email", "from_email", "author"):
+        v = attrs.get(key)
+        if isinstance(v, str):
+            raw.append(v)
+    for key in ("to_emails", "cc_emails"):
+        v = attrs.get(key)
+        if isinstance(v, str):
+            raw.extend(v.replace(";", ",").split(","))
+        elif isinstance(v, list):
+            raw.extend(x for x in v if isinstance(x, str))
+    for r in raw:
+        domains.add(_domain_of(r))
+    for key in ("domain", "company_domain", "org_domain"):
+        domains.add(_bare_domain(attrs.get(key)))
+    return {
+        d for d in domains
+        if d and d not in FREEMAIL_DOMAINS and d not in TENANT_EMAIL_DOMAINS
+    }
+
+
+def domain_label(domain: str) -> str | None:
+    """Registrable label of a domain — 'lego' from 'lego.com', 'boots' from
+    'boots.co.uk'. Used only for the name↔domain match below."""
+    if not domain:
+        return None
+    parts = domain.lower().strip(".").split(".")
+    if len(parts) < 2:
+        return None
+    if ".".join(parts[-2:]) in _MULTI_LABEL_TLDS and len(parts) >= 3:
+        return parts[-3]
+    return parts[-2]
+
+
+def match_org_domain(org_name: str, domains: set[str]) -> str | None:
+    """Return the one envelope domain that deterministically belongs to this
+    org — i.e. whose registrable label matches the org's name — else None.
+
+    This is the precision guard that makes envelope-derived stamping SAFE: an
+    email *from* acme.com that merely mentions "Globex" must not stamp acme.com
+    onto Globex. We match only when the domain's label is a whole name token
+    ("lego" ∈ "LEGO Group") or equals the de-spaced name ("mastercard" ↔
+    "Mastercard"). If two different domains match (genuine ambiguity), return
+    None and let fusion decide rather than guess.
+
+    We deliberately do NOT prefix-match the squished name. A `startswith`
+    rule (the original #111 form) over-fires whenever one org's name starts
+    with another org's label — "apple".startswith on "applebees" stamps
+    apple.com onto Applebee's; likewise lego.com→Legoland, micro.com→Microsoft.
+    Because the stamp becomes a resolution alias, that mis-merges two real orgs
+    at INGEST (immediate, not behind the Fusion Drive's dry-run/audit gate) —
+    the one path here that can silently fuse distinct orgs. The legitimate
+    "LEGO Group" case is already covered by the whole-token rule, so the prefix
+    clause added only false-positive surface for no real gain."""
+    if not org_name or not domains:
+        return None
+    norm = normalize_surface_form(org_name)
+    tokens = {t for t in re.split(r"[^a-z0-9]+", norm) if len(t) >= 2}
+    squished = norm.replace(" ", "")
+    matched: set[str] = set()
+    for d in domains:
+        label = domain_label(d)
+        if not label or len(label) < 2:
+            continue
+        if label in tokens or label == squished:
+            matched.add(d)
+    return next(iter(matched)) if len(matched) == 1 else None
+
+
+# System-of-record record-type → core ontology type. A SoR event (a CRM record,
+# a finance record, …) represents ONE primary entity of a known type; we map the
+# producer's record-type tag onto the core type so we can key that entity on the
+# record's external id. Extend per connector as new SoRs land.
+_HUBSPOT_KIND_TO_TYPE = {"company": "org", "contact": "person"}
+
+
+def event_record_subject(attrs: dict[str, Any] | None) -> tuple[str | None, str | None]:
+    """For an event that IS a system-of-record record, return
+    `(core_type, external_id)` for its single primary entity — else `(None, None)`.
+
+    The external id (`source_id` — already a composite `system:kind:id`, e.g.
+    `hubspot:company:12345`) is the registry's FALLBACK org/person hard key
+    (A.1): used when no email/domain resolves, so re-importing the same record
+    converges to one node (idempotency) and a domainless SoR entity isn't
+    re-minted on every sync. Only fires for records whose type maps to a core
+    type (company→org, contact→person); deal/ticket/custom-plugin types return
+    None (they aren't core graph entities). The caller additionally requires the
+    event to extract exactly ONE entity of `core_type` before keying on this —
+    so a record that also mentions other orgs/people never mis-stamps them."""
+    if not attrs:
+        return (None, None)
+    external_id = attrs.get("source_id")
+    if not isinstance(external_id, str) or not external_id.strip():
+        return (None, None)
+    hubspot_kind = attrs.get("hubspot_kind")
+    if isinstance(hubspot_kind, str):
+        core = _HUBSPOT_KIND_TO_TYPE.get(hubspot_kind.lower())
+        if core:
+            return (core, external_id.strip())
+    return (None, None)
+
+
+def org_node_id_key(entity_type: str, name: str, stamped_domain: str | None) -> str:
+    """The string `entity_id()` hashes to mint an entity's NODE id — its domain
+    hard key when we resolved one (org), else its name.
+
+    This is the id-level complement to the alias stamp (`match_org_domain`):
+    the stamp makes the domain a resolution *alias* (caught by the upsert
+    SELECT/lock); keying the node *id* on the domain makes convergence
+    DETERMINISTIC and order-independent. Every event that resolves the same
+    domain mints the SAME id, so they collapse to ONE node via `ON CONFLICT
+    (id)` even if the SELECT and the advisory lock both miss — and a re-distill
+    of the corpus yields exactly one org node per domain regardless of event
+    order, instead of a name-keyed pile Fusion has to chase (the entity-ontology
+    spine's "the big structural fix"). Org-only for now; person→email and
+    external-id are the symmetric follow-ups. Falls back to the name for
+    non-orgs and for orgs we couldn't resolve a domain for (prose-only orgs)."""
+    if entity_type == "org" and stamped_domain:
+        return stamped_domain
+    return name
+
+
 def upsert_entities(
     conn: psycopg.Connection,
     arena: str,
@@ -809,6 +1020,7 @@ def upsert_entities(
     disclosure_class: str,
     entities: list[dict],
     event_time: datetime | None,
+    event_attrs: dict[str, Any] | None = None,
 ) -> dict[str, str]:
     """Alias-aware insert (or merge) of entities; returns a name→id
     map so facts and relationships can link to the inserted rows.
@@ -836,10 +1048,28 @@ def upsert_entities(
        serialises concurrent writers (sync + async on the same event)
        on the same surface form. (RFC steps 2 + 2a.)
 
-    MIRROR of extractor-sync/server.py:_upsert_entities — same
-    resolution algorithm. Kept as separate Python because the sync
-    extractor uses async psycopg and the async worker uses sync
-    psycopg; the SQL is identical.
+    3. **Org-domain hard-key stamping + id keying** — when `event_attrs` carries
+       the structured envelope, the corporate email domain that matches an `org`
+       entity's name is stamped onto it as a resolution alias (so domain-sharing
+       orgs merge via the alias-overlap path above) and as `attributes.domain`
+       on the node. The new node's *id* is then minted from that domain
+       (`org_node_id_key`) rather than the name, so same-domain orgs converge to
+       ONE id deterministically — robust to a SELECT/lock miss and order-
+       independent under a re-distill. This is the deterministic hard key the
+       registry wants for org; see `event_org_domains`/`match_org_domain` and
+       entity-ontology-the-spine.md §IV.
+
+    4. **SoR external-id fallback** — when the event IS a system-of-record record
+       (`event_record_subject`) and extracts exactly ONE entity of the record's
+       core type, that subject — if it has no email/domain hard key — is keyed on
+       the record's external id and carries `attributes.external_id`, so
+       re-imports of the same record converge (registry precedence: email/domain
+       → external-id → name). email/domain still win when present.
+
+    MIRROR of extractor-sync/server.py:_upsert_entities for the resolution
+    algorithm. The sync pass never mints `org` entities (it emits
+    person/document from the envelope), so org-domain stamping is async-only and
+    leaves the entity-id parity test untouched.
 
     Returns name→id where `name` is the LLM-emitted surface form
     (canonical) so facts/relationships using the same surface form
@@ -847,6 +1077,22 @@ def upsert_entities(
     name_to_id: dict[str, str] = {}
     if not entities:
         return name_to_id
+    # Corporate domains in this event's structured envelope — the deterministic
+    # source of org hard keys (computed once per event, not per entity).
+    org_domains = event_org_domains(event_attrs)
+    # System-of-record external-id fallback: if this event IS a single record
+    # (e.g. a HubSpot company/contact) AND it extracts exactly ONE entity of the
+    # record's core type, that entity is the record's subject and may be keyed on
+    # the record's external id (the registry fallback, after email/domain). The
+    # exactly-one guard is the precision gate — a record that also names other
+    # orgs/people leaves `subject_ext_id` None so nothing is mis-stamped.
+    subject_type, subject_ext_id = event_record_subject(event_attrs)
+    if subject_type:
+        n_of_type = sum(
+            1 for e in entities if (e.get("type") or "other").lower() == subject_type
+        )
+        if n_of_type != 1:
+            subject_ext_id = None
     with conn.cursor() as cur:
         for e in entities:
             etype = (e.get("type") or "other").lower()
@@ -858,6 +1104,27 @@ def upsert_entities(
                 continue
             aliases = [a for a in (e.get("aliases") or []) if a]
 
+            # Hard-key stamps for THIS entity, merged onto the node's attributes
+            # and (for domain) into the resolution aliases. Adding domain to
+            # aliases before forms are computed is deliberate — that's what makes
+            # the alias-overlap merge pick it up.
+            attrs_patch: dict[str, str] = {}
+            stamped_domain: str | None = None
+            if etype == "org" and org_domains:
+                stamped_domain = match_org_domain(name, org_domains)
+                if stamped_domain:
+                    if stamped_domain not in aliases:
+                        aliases.append(stamped_domain)
+                    attrs_patch["domain"] = stamped_domain
+            # SoR external-id: the single subject of a record event carries the
+            # record's external id (resolution alias + `attributes.external_id`).
+            is_record_subject = bool(subject_ext_id) and etype == subject_type
+            if is_record_subject and subject_ext_id:
+                if subject_ext_id not in aliases:
+                    aliases.append(subject_ext_id)
+                attrs_patch["external_id"] = subject_ext_id
+            attrs_update = json.dumps(attrs_patch)
+
             # 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
@@ -902,17 +1169,46 @@ def upsert_entities(
                     UPDATE entities SET
                       aliases = ARRAY(SELECT DISTINCT UNNEST(aliases || %s::text[])),
                       provenance_event_ids = ARRAY(SELECT DISTINCT UNNEST(provenance_event_ids || %s::text[])),
+                      -- Merge the org-domain hard key (no-op for the `{}` default
+                      -- on non-orgs / unmatched orgs; never clobbers an existing key).
+                      attributes = entities.attributes || %s::jsonb,
                       -- Widen the seen-window with this event's SOURCE
                       -- time, not NOW(): newest evidence = newest source.
                       last_seen = GREATEST(last_seen, COALESCE(%s, NOW())),
                       first_seen = LEAST(first_seen, COALESCE(%s, NOW()))
                     WHERE id = %s
                     """,
-                    (aliases, [event_id], event_time, event_time, eid),
+                    (aliases, [event_id], attrs_update, event_time, event_time, eid),
                 )
             else:
-                # 3b. No match — insert new.
-                eid = entity_id(arena, etype, name)
+                # 3b. No match — insert new. Key the node on its HARD KEY so the
+                # same real thing mints the SAME id and converges via ON CONFLICT
+                # even if the SELECT/lock missed (task #2): org → its resolved
+                # DOMAIN (org_node_id_key); person → its EMAIL via the SHARED
+                # person_id_key, so this matches the sync pass byte-for-byte
+                # (sync mints person nodes at ingest — see entity_id.py). Email
+                # is carried as an alias on async persons (LLM-promoted); pull it
+                # back out here. Everything else falls back to the name.
+                if etype == "person":
+                    person_email = next(
+                        (a for a in aliases if a and "@" in a and " " not in a),
+                        None,
+                    )
+                    id_key = person_id_key(name, person_email)
+                    has_hard_key = person_email is not None
+                elif etype == "org":
+                    id_key = org_node_id_key(etype, name, stamped_domain)
+                    has_hard_key = stamped_domain is not None
+                else:
+                    id_key = name
+                    has_hard_key = False
+                # FALLBACK: a SoR record's single subject with no email/domain
+                # keys on the record's external id, so re-imports of that record
+                # converge to one node (registry precedence: email/domain →
+                # external-id → name). email/domain still win when present.
+                if not has_hard_key and is_record_subject and subject_ext_id:
+                    id_key = subject_ext_id
+                eid = entity_id(arena, etype, id_key)
                 # Fusion Drive born-salience: a numeric-ID-as-person (classic
                 # 7B junk that slips past noise_filter, e.g. "1716801984") is
                 # born near the floor so the decay pass can evict it on a short
@@ -926,10 +1222,10 @@ def upsert_entities(
                     INSERT INTO entities (
                       id, arena, entity_type, canonical_name, aliases,
                       provenance_event_ids, participant_set, disclosure_class, salience,
-                      first_seen, last_seen
+                      attributes, first_seen, last_seen
                     ) VALUES (
                       %s, %s, %s, %s, %s, %s, %s, %s::disclosure_class, %s,
-                      COALESCE(%s, NOW()), COALESCE(%s, NOW())
+                      %s::jsonb, COALESCE(%s, NOW()), COALESCE(%s, NOW())
                     )
                     ON CONFLICT (id) DO UPDATE SET
                       aliases = (
@@ -938,6 +1234,8 @@ def upsert_entities(
                       provenance_event_ids = (
                         SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
                       ),
+                      -- merge the org-domain hard key (no-op for `{}`)
+                      attributes = entities.attributes || EXCLUDED.attributes,
                       -- re-corroboration can only RAISE salience, never lower it
                       salience = GREATEST(entities.salience, EXCLUDED.salience),
                       -- widen the seen-window on SOURCE time, not NOW()
@@ -947,13 +1245,36 @@ def upsert_entities(
                     (
                         eid, arena, etype, name, aliases,
                         [event_id], participant_set, disclosure_class, _sal,
-                        event_time, event_time,
+                        attrs_update, event_time, event_time,
                     ),
                 )
             name_to_id[name] = eid
     return name_to_id
 
 
+def fact_source(event: dict[str, Any]) -> str | None:
+    """Derive the originating SOURCE label to stamp onto a fact.
+
+    Prefer the finer producer label `attributes.source` (gmail / slack /
+    hubspot / granola / drive / github) over the coarse `source_kind`
+    enum (chat / note / system / ...), because SoR-drift detection needs
+    "CRM vs email" granularity, which the enum can't express (both gmail
+    and a draft are `note`; both HubSpot and an ERP snapshot are
+    `system`). Fall back to `source_kind` when the producer didn't supply
+    a finer label, and to None only when neither is present — NULL ==
+    source-unknown, matching the pre-009 state of existing rows so the
+    nullable column never lies. Pure + total: never raises, so it can't
+    break the distill path; the caller stamps whatever it returns."""
+    attrs = event.get("attributes") or {}
+    src = attrs.get("source")
+    if isinstance(src, str) and src.strip():
+        return src.strip()
+    kind = event.get("source_kind")
+    if isinstance(kind, str) and kind.strip():
+        return kind.strip()
+    return None
+
+
 def upsert_facts(
     conn: psycopg.Connection,
     arena: str,
@@ -964,6 +1285,7 @@ def upsert_facts(
     name_to_id: dict[str, str],
     event_time: datetime | None,
     due_at: datetime | None = None,
+    source: str | None = None,
 ) -> int:
     """Facts are content-hashed on (arena, statement). Same statement
     extracted from any event in the arena converges to the same row,
@@ -989,7 +1311,15 @@ def upsert_facts(
     corroborating events: facts have no `last_seen`, so #92's decay uses
     `asserted_at` as the recency clock and resets it on re-corroboration
     — order-stable regardless of distill order. `due_at` (the source
-    event's structured deadline, if any) populates `effective_until`."""
+    event's structured deadline, if any) populates `effective_until`.
+
+    `source` is the originating producer label (`fact_source()` — finer
+    `attributes.source` else coarse `source_kind`), stamped so a reader
+    can tell "this came from the CRM" from "this came from an email" —
+    the foundation for SoR-drift detection. Accrete-only on conflict:
+    COALESCE keeps the first-known source and only fills it when a prior
+    extraction left it NULL, so corroboration never rewrites provenance
+    (and a NULL — pre-009 rows, or a source-less event — stays NULL)."""
     if not facts:
         return 0
     inserted = 0
@@ -1015,11 +1345,11 @@ def upsert_facts(
                   id, arena, category, subject_entity_id, predicate,
                   object_entity_id, statement, provenance_event_ids,
                   stage, confidence, participant_set, disclosure_class, salience,
-                  asserted_at, effective_until
+                  asserted_at, effective_until, source
                 ) VALUES (
                   %s, %s, %s, %s, %s, %s, %s, %s,
                   'provisional'::extraction_stage, %s, %s, %s::disclosure_class, %s,
-                  COALESCE(%s, NOW()), %s
+                  COALESCE(%s, NOW()), %s, %s
                 )
                 ON CONFLICT (id) DO UPDATE SET
                   provenance_event_ids = (
@@ -1057,7 +1387,11 @@ def upsert_facts(
                   -- This also makes it order-stable (independent of
                   -- distill order). EXCLUDED.asserted_at is the
                   -- COALESCE(event_time, NOW()) from the INSERT above.
-                  asserted_at = GREATEST(facts.asserted_at, EXCLUDED.asserted_at)
+                  asserted_at = GREATEST(facts.asserted_at, EXCLUDED.asserted_at),
+                  -- Accrete-only: keep the first-known source, only fill
+                  -- it if a prior extraction left it NULL. Corroboration
+                  -- must not rewrite where the fact first came from.
+                  source = COALESCE(facts.source, EXCLUDED.source)
                 """,
                 (
                     _content_id(arena, stmt),
@@ -1074,6 +1408,7 @@ def upsert_facts(
                     _fsal,
                     event_time,
                     due_at,
+                    source,
                 ),
             )
             inserted += 1
@@ -1551,15 +1886,20 @@ async def process_batch(
             # behaviour). Only `attributes.due_at` is honoured; we do NOT
             # guess deadlines from free text here.
             due_at = parse_source_time((event.get("attributes") or {}).get("due_at"))
+            # ORIGINATING SOURCE of this event, stamped onto its facts so
+            # downstream can tell CRM-asserted from email-asserted (the
+            # SoR-drift foundation). Finer `attributes.source` else coarse
+            # `source_kind`; None ⇒ column stays NULL (source-unknown).
+            src = fact_source(event)
 
             try:
                 name_to_id = upsert_entities(
                     conn, arena, event_id, participant_set, disclosure, ents,
-                    event_time,
+                    event_time, event.get("attributes"),
                 )
                 n_facts = upsert_facts(
                     conn, arena, event_id, participant_set, disclosure, facts, name_to_id,
-                    event_time, due_at,
+                    event_time, due_at, src,
                 )
                 n_rels = upsert_relationships(
                     conn, arena, event_id, participant_set, disclosure, rels, name_to_id,

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

@@ -55,3 +55,23 @@ def entity_id(arena: str, entity_type: str, canonical_name: str) -> str:
     """
     key = f"{arena}|{entity_type}|{normalize_surface_form(canonical_name)}"
     return "e_" + hashlib.sha256(key.encode()).hexdigest()[:24]
+
+
+def person_id_key(name: str | None, email: str | None) -> str:
+    """The string `entity_id()` should hash to mint a PERSON's node id — the
+    EMAIL (the person's deterministic hard key) when present, else the name.
+
+    Lives HERE, in the byte-identical shared file, BECAUSE both extractors mint
+    person nodes and must agree: the sync pass builds them from the envelope at
+    ingest (it has the email), the async pass builds them from prose (email
+    promoted to an alias). Keying both on the email means the same person mints
+    the SAME id from either pass and in any processing order — converging to one
+    node instead of sync's name-keyed node and async's node racing, or a
+    re-distill re-homing them differently. The name is the fallback for a person
+    with no email (Fusion still merges those fuzzily). `entity_id()` normalises
+    (lowercase + trim) the result, so casing/whitespace variants of an email
+    collapse. (Org keying is the async-only `org_node_id_key`; person keying is
+    cross-pass, so it belongs in this parity-guarded file.)
+    """
+    e = (email or "").strip()
+    return e if e else (name or "")

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

@@ -32,7 +32,7 @@ from typing import Any
 
 # Canonical entity-ID scheme — byte-identical copy in extractor-async (entity_id.py).
 from confidence import born_salience
-from entity_id import entity_id, normalize_surface_form  # noqa: F401
+from entity_id import entity_id, normalize_surface_form, person_id_key  # noqa: F401
 # Source-time parsing — byte-identical copy in extractor-async (source_time.py).
 from source_time import event_source_time
 
@@ -250,12 +250,17 @@ def _person_entity(
     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).
+    # Prefer name as canonical_name (the human-readable display) 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
+    # …but key the node ID on the EMAIL hard key when present (task #2), via the
+    # SHARED person_id_key so sync (here) and the async pass mint the SAME id for
+    # the same person regardless of order — deterministic convergence, not a
+    # name-vs-email race. Display name and id key are now decoupled.
+    id_key = person_id_key(name, email)
     aliases_set: set[str] = set()
     if name:
         aliases_set.add(name)
@@ -266,7 +271,7 @@ def _person_entity(
             aliases_set.add(a)
 
     return {
-        "id": _entity_id(req.arena, "person", canonical),
+        "id": _entity_id(req.arena, "person", id_key),
         "arena": req.arena,
         "entity_type": "person",
         "canonical_name": canonical,

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

@@ -62,16 +62,21 @@ def stub_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."""
+    """When both name and email present → display name is the canonical_name,
+    but the node ID keys on the EMAIL hard key (task #2), with 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")
+    # Id is derived from the EMAIL hard key (not the name) — so the same person
+    # converges across passes/sources/spellings. Display name is decoupled.
+    assert e["id"] == sync_server._entity_id(
+        "tenant:test", "person", "carly@example.com"
+    )
+    assert e["id"] != sync_server._entity_id("tenant:test", "person", "Carly Snider")
 
 
 def test_person_entity_email_only(stub_req) -> None:

package/packages/memory-engine-v2/org-model/migrations/009_fact_source.sql

@@ -0,0 +1,24 @@
+-- 009: stamp the originating SOURCE onto each fact (SoR-drift foundation).
+--
+-- The distiller extracts facts from events but drops WHICH SOURCE each
+-- fact came from. The source lives on the event (`events.source_kind` +
+-- the finer `attributes.source`) but never reaches the `facts` table, so
+-- a reader can't tell "this came from the CRM" from "this came from an
+-- email". That distinction is the foundation for system-of-record drift
+-- detection (e.g. CRM says a deal is active, a newer email says it was
+-- rejected). This column makes the signal available; the drift READ /
+-- detection path is an explicit follow-up and is NOT built here.
+--
+-- Forward-only + additive, per 001_init.sql header note 1 ("to iterate
+-- the schema, add columns; never alter existing ones"). The column is
+-- NULLABLE with no backfill: every historical fact and every existing
+-- reader is unaffected (NULL = source-unknown, the pre-009 state). New
+-- distillations stamp it from the finer `attributes.source` when the
+-- producer supplied one, else the coarse `source_kind` enum value — see
+-- `fact_source()` in extractor-async/worker.py for the derivation rule.
+--
+-- TEXT (not the `source_kind` enum) on purpose: we want the finer
+-- producer label (gmail / slack / hubspot / granola / drive / github)
+-- where available, which is exactly the granularity SoR-drift needs and
+-- which the enum can't represent.
+ALTER TABLE facts ADD COLUMN IF NOT EXISTS source TEXT;

package/packages/memory-engine-v2/tests/test_entity_id_parity.py

@@ -55,3 +55,27 @@ def test_identical_output_across_copies():
     for arena, etype, name in cases:
         assert a.entity_id(arena, etype, name) == b.entity_id(arena, etype, name)
         assert a.normalize_surface_form(name) == b.normalize_surface_form(name)
+
+
+def test_person_id_key_parity_and_behaviour():
+    """person_id_key is the cross-pass person hard key — it MUST behave
+    identically in both copies (it's why it lives in the shared file), and it
+    must prefer the email so a person mints the same id from either extractor."""
+    a = _load(_SYNC, "entity_id_sync2")
+    b = _load(_ASYNC, "entity_id_async2")
+    key_cases = [
+        ("Johann Boedecker", "johann@pentatonic.com"),
+        ("Johann Boedecker", None),
+        (None, "carly@pact.org"),
+        ("  Ben Gordon  ", "  Ben@Acme.com  "),
+        (None, None),
+    ]
+    for name, email in key_cases:
+        assert a.person_id_key(name, email) == b.person_id_key(name, email)
+    # Prefers the email; falls back to the name.
+    assert a.person_id_key("Johann", "johann@p.com") == "johann@p.com"
+    assert a.person_id_key("Johann", None) == "Johann"
+    # Name-variants with the same email → the SAME node id (the whole point).
+    id1 = a.entity_id("arena1", "person", a.person_id_key("Johann Boedecker", "j@p.com"))
+    id2 = a.entity_id("arena1", "person", a.person_id_key("BOEDECKER, JOHANN", "j@p.com"))
+    assert id1 == id2