@pentatonic-ai/ai-agent-sdk 0.10.18 → 0.10.20

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

@@ -0,0 +1,218 @@
+"""Structured diff between two extractions (student vs teacher gold).
+
+Replaces the crude agreement proxies we'd been quoting (entity-name-exact-match;
+word-Jaccard on whole statements) with a STRUCTURED comparison that:
+
+  - matches entities on fuzzy name + compatible type (not exact lowercased string,
+    which penalised "Acme" vs "Acme Corp" / normalisation variants),
+  - matches facts on their s·p·o STRUCTURE plus the statement as a fallback
+    (not bag-of-words on the statement, which ignored who-did-what),
+  - matches relationships as (from, type, to) triples,
+  - reports precision / recall / F1 PER AXIS, and facts broken down PER CATEGORY
+    (so `decision`/`commitment` agreement is isolated — the cascade's
+    high-value gate question).
+
+Deterministic + stdlib-only (difflib) so it runs offline, in CI, and on any box
+without a GPU. Semantic-embedding matching is a deliberate non-goal here: a
+deterministic structural diff is the defensible, un-game-able baseline (no model
+judging another model's output); an embedding tiebreak can layer on later if the
+fuzzy threshold proves too strict.
+
+Shapes (mirror _parse_guided_json output):
+  entity       = {"name", "type", "aliases"?: [emails]}
+  fact         = {"category", "subject", "predicate", "object"?, "statement"}
+  relationship = {"from", "to", "type"}
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from typing import Any
+
+# Org/legal-form suffixes stripped before name comparison so "Acme" == "Acme Inc".
+_ORG_SUFFIX = re.compile(
+    r"\b(inc|incorporated|ltd|limited|llc|llp|plc|corp|corporation|co|gmbh|ag|sa|"
+    r"sas|bv|nv|pty|group|holdings?|company)\b\.?",
+    re.IGNORECASE,
+)
+_NONWORD = re.compile(r"[^a-z0-9 ]+")
+_WS = re.compile(r"\s+")
+
+
+def normalize_name(s: str | None) -> str:
+    """Lowercase, drop punctuation + org suffixes, collapse whitespace."""
+    if not s:
+        return ""
+    s = s.lower()
+    s = _ORG_SUFFIX.sub(" ", s)
+    s = _NONWORD.sub(" ", s)
+    return _WS.sub(" ", s).strip()
+
+
+def _tokens(s: str) -> set[str]:
+    return set(normalize_name(s).split())
+
+
+def sim(a: str | None, b: str | None) -> float:
+    """Similarity in [0,1]: max of char-level ratio and token-set Jaccard on the
+    normalised strings. The token-set arm rewards word overlap regardless of
+    order/length ("ship the Q3 release" vs "Q3 release will ship"); the
+    char-ratio arm rewards near-identical short strings."""
+    na, nb = normalize_name(a), normalize_name(b)
+    if not na and not nb:
+        return 1.0
+    if not na or not nb:
+        return 0.0
+    if na == nb:
+        return 1.0
+    char = SequenceMatcher(None, na, nb).ratio()
+    ta, tb = set(na.split()), set(nb.split())
+    jac = len(ta & tb) / len(ta | tb) if (ta | tb) else 0.0
+    return max(char, jac)
+
+
+@dataclass
+class PRF:
+    """Precision/recall/F1 for one axis. n_gold/n_pred are the item counts."""
+    n_gold: int
+    n_pred: int
+    matched: int
+
+    @property
+    def precision(self) -> float:
+        if self.n_pred == 0:
+            return 1.0 if self.n_gold == 0 else 0.0
+        return self.matched / self.n_pred
+
+    @property
+    def recall(self) -> float:
+        if self.n_gold == 0:
+            return 1.0 if self.n_pred == 0 else 0.0
+        return self.matched / self.n_gold
+
+    @property
+    def f1(self) -> float:
+        p, r = self.precision, self.recall
+        return 2 * p * r / (p + r) if (p + r) else (1.0 if self.n_gold == 0 and self.n_pred == 0 else 0.0)
+
+    def as_dict(self) -> dict[str, float | int]:
+        return {
+            "n_gold": self.n_gold, "n_pred": self.n_pred, "matched": self.matched,
+            "precision": round(self.precision, 4), "recall": round(self.recall, 4),
+            "f1": round(self.f1, 4),
+        }
+
+
+def _greedy_match(gold: list, pred: list, score_fn, threshold: float) -> int:
+    """Count matched gold items via greedy 1:1 alignment. All (gold, pred) pairs
+    scored, sorted desc, claimed highest-first so each item matches at most once.
+    Deterministic (stable sort, then index tiebreak)."""
+    pairs = []
+    for gi, g in enumerate(gold):
+        for pi, p in enumerate(pred):
+            s = score_fn(g, p)
+            if s >= threshold:
+                pairs.append((-s, gi, pi))
+    pairs.sort()
+    used_g: set[int] = set()
+    used_p: set[int] = set()
+    matched = 0
+    for _, gi, pi in pairs:
+        if gi in used_g or pi in used_p:
+            continue
+        used_g.add(gi)
+        used_p.add(pi)
+        matched += 1
+    return matched
+
+
+# ── per-item scorers ─────────────────────────────────────────────────────
+
+def _entity_score(g: dict, p: dict) -> float:
+    """Name similarity, gated by type compatibility (equal, or either side
+    'other'/missing — the LLMs disagree on type far more than on identity)."""
+    gt = (g.get("type") or "").lower()
+    pt = (p.get("type") or "").lower()
+    if gt and pt and gt != pt and "other" not in (gt, pt):
+        return 0.0
+    return sim(g.get("name"), p.get("name"))
+
+
+def _fact_score(g: dict, p: dict) -> float:
+    """Structural s·p·o similarity, OR statement similarity as a fallback.
+    Structure: mean of subject/predicate/object sims (object absent on both =
+    neutral 1.0 for that term). Take the max of structural and statement so a
+    well-phrased statement still matches even if s/p/o were split differently."""
+    subj = sim(g.get("subject"), p.get("subject"))
+    pred = sim(g.get("predicate"), p.get("predicate"))
+    go, po = g.get("object"), p.get("object")
+    obj = 1.0 if not go and not po else sim(go, po)
+    structural = (subj + pred + obj) / 3
+    statement = sim(g.get("statement"), p.get("statement"))
+    return max(structural, statement)
+
+
+def _rel_score(g: dict, p: dict) -> float:
+    """(from, type, to) triple: mean of the three term sims."""
+    return (sim(g.get("from"), p.get("from"))
+            + sim(g.get("type"), p.get("type"))
+            + sim(g.get("to"), p.get("to"))) / 3
+
+
+# ── public API ─────────────────────────────────────────────────────────────
+
+ENTITY_THRESHOLD = 0.85
+FACT_THRESHOLD = 0.60
+REL_THRESHOLD = 0.60
+
+
+def diff_axis(gold: list[dict], pred: list[dict], kind: str) -> PRF:
+    """Match one axis ('entities' | 'facts' | 'relationships'); return PRF."""
+    scorer, thr = {
+        "entities": (_entity_score, ENTITY_THRESHOLD),
+        "facts": (_fact_score, FACT_THRESHOLD),
+        "relationships": (_rel_score, REL_THRESHOLD),
+    }[kind]
+    matched = _greedy_match(gold, pred, scorer, thr)
+    return PRF(n_gold=len(gold), n_pred=len(pred), matched=matched)
+
+
+def _facts_in(extraction: dict, categories: set[str] | None) -> list[dict]:
+    facts = extraction.get("facts") or []
+    if categories is None:
+        return facts
+    return [f for f in facts if (f.get("category") or "").lower() in categories]
+
+
+def diff_extractions(
+    gold: dict, pred: dict, fact_categories: set[str] | None = None
+) -> dict[str, Any]:
+    """Full structured diff. `gold`/`pred` are extraction dicts. Returns per-axis
+    PRF dicts plus per-fact-category PRF. `fact_categories`, if given, also
+    reports a 'facts_filtered' PRF over just those categories (e.g.
+    {'decision','commitment'} for the high-value-gate question)."""
+    out: dict[str, Any] = {
+        "entities": diff_axis(gold.get("entities") or [], pred.get("entities") or [], "entities").as_dict(),
+        "facts": diff_axis(gold.get("facts") or [], pred.get("facts") or [], "facts").as_dict(),
+        "relationships": diff_axis(
+            gold.get("relationships") or [], pred.get("relationships") or [], "relationships"
+        ).as_dict(),
+    }
+    # per-category fact breakdown
+    cats = {(f.get("category") or "").lower() for f in (gold.get("facts") or [])}
+    cats |= {(f.get("category") or "").lower() for f in (pred.get("facts") or [])}
+    cats.discard("")
+    by_cat: dict[str, Any] = {}
+    for c in sorted(cats):
+        g = _facts_in(gold, {c})
+        p = _facts_in(pred, {c})
+        by_cat[c] = diff_axis(g, p, "facts").as_dict()
+    out["facts_by_category"] = by_cat
+    if fact_categories is not None:
+        g = _facts_in(gold, fact_categories)
+        p = _facts_in(pred, fact_categories)
+        out["facts_filtered"] = diff_axis(g, p, "facts").as_dict()
+        out["facts_filtered_categories"] = sorted(fact_categories)
+    return out

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

@@ -0,0 +1,78 @@
+"""Unit tests for the email-alias guard (_email_plausibly_belongs).
+
+Pins the live pollution case (the "Johann Boedecker" node, 2026-06-22): keep the
+person's own addresses; drop the bystander emails (a hotel, newsletters, unrelated
+gmails) the LLM stapled on from co-occurring documents.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+_THIS = Path(__file__).resolve().parent
+
+
+def _load(name="extractor_async_worker_aliasguard"):
+    spec = importlib.util.spec_from_file_location(name, _THIS / "worker.py")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+try:
+    worker = _load()
+except ImportError as e:
+    pytest.skip(f"extractor-async deps unavailable: {e}", allow_module_level=True)
+
+belongs = lambda n, e: worker._email_plausibly_belongs(n, e)
+
+
+# ── KEEP: the person's own addresses ─────────────────────────────────────
+@pytest.mark.parametrize("email", [
+    "johann@pentatonic.com",
+    "johann.boedecker@pentatonic.com",
+    "boedeckerjohann@gmail.com",
+    "JOHANN@pentatonic.com",          # case-insensitive
+    "jb@pentatonic.com",              # initials
+    "j.boedecker@pentatonic.com",     # surname token
+])
+def test_keeps_owner_emails(email):
+    assert belongs("Johann Boedecker", email) is True
+
+
+# ── DROP: the actual bystander emails found on the live Johann node ──────
+@pytest.mark.parametrize("email", [
+    "reservations.nyc@acehotel.com",
+    "marketingadmin@sustainablebrands.com",
+    "martinvasquez87@gmail.com",
+    "schwaabd@yahoo.de",
+    "cvanderlip@redish.com",
+    "leechihshan33@gmail.com",
+])
+def test_drops_bystander_emails(email):
+    assert belongs("Johann Boedecker", email) is False
+
+
+# ── edges ────────────────────────────────────────────────────────────────
+def test_initials_either_order():
+    assert belongs("Johann Boedecker", "bj@pentatonic.com") is True   # reversed initials
+
+
+def test_no_usable_name_does_not_overfilter():
+    # a bare/empty name has nothing to check against → keep (don't strip)
+    assert belongs("", "anything@x.com") is True
+    assert belongs("J", "anything@x.com") is True  # single letter < 2 → no tokens
+
+
+def test_surname_only_person_keeps_surname_email():
+    assert belongs("Vickers", "will.vickers@vickers-oil.com") is True
+    assert belongs("Vickers", "reservations.nyc@acehotel.com") is False
+
+
+def test_guard_flag_default_on():
+    assert worker.EMAIL_ALIAS_GUARD is True

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

@@ -0,0 +1,180 @@
+"""Unit tests for the structured-diff agreement metric (extraction_diff).
+
+Pins the behaviours that make it a real metric rather than the old proxies:
+fuzzy/normalised name matching, structural s·p·o fact matching, per-axis P/R/F1,
+per-category fact breakdown, and the high-value filtered view.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+_THIS = Path(__file__).resolve().parent
+
+
+def _load(name="extraction_diff_mod"):
+    spec = importlib.util.spec_from_file_location(name, _THIS / "extraction_diff.py")
+    mod = importlib.util.module_from_spec(spec)
+    # Register before exec so @dataclass's type resolution (which walks
+    # sys.modules[cls.__module__]) works under the importlib custom-name load
+    # on Python 3.12+/3.14. A normal `import extraction_diff` (CI/prod) is fine.
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+ed = _load()
+
+
+# ── normalize_name / sim ─────────────────────────────────────────────────
+
+def test_normalize_strips_org_suffix_and_punct():
+    assert ed.normalize_name("Acme Corp.") == "acme"
+    assert ed.normalize_name("Acme, Inc.") == "acme"
+    assert ed.normalize_name("ACME Limited") == "acme"
+
+
+def test_sim_normalisation_variants_are_high():
+    # the exact-string proxy scored these 0; structured sim should be ~1.
+    assert ed.sim("Acme", "Acme Corp") >= 0.99
+    assert ed.sim("Acme Inc.", "ACME") >= 0.99
+
+
+def test_sim_token_overlap_order_invariant():
+    assert ed.sim("ship the Q3 release", "Q3 release will ship") >= 0.6
+
+
+def test_sim_unrelated_low():
+    assert ed.sim("Acme", "Globex") < 0.5
+
+
+def test_sim_both_empty_is_one():
+    assert ed.sim("", "") == 1.0
+    assert ed.sim(None, "x") == 0.0
+
+
+# ── PRF arithmetic ───────────────────────────────────────────────────────
+
+def test_prf_basic():
+    prf = ed.PRF(n_gold=4, n_pred=5, matched=3)
+    assert prf.recall == 0.75
+    assert prf.precision == 0.6
+    assert round(prf.f1, 3) == 0.667
+
+
+def test_prf_empty_both_is_perfect():
+    prf = ed.PRF(n_gold=0, n_pred=0, matched=0)
+    assert prf.precision == 1.0 and prf.recall == 1.0 and prf.f1 == 1.0
+
+
+def test_prf_pred_without_gold_is_zero_precision():
+    prf = ed.PRF(n_gold=0, n_pred=2, matched=0)
+    assert prf.precision == 0.0
+
+
+# ── entity matching ──────────────────────────────────────────────────────
+
+def test_entity_match_fuzzy_name_same_type():
+    g = [{"name": "Acme Corp", "type": "org"}]
+    p = [{"name": "Acme", "type": "org"}]
+    prf = ed.diff_axis(g, p, "entities")
+    assert prf.matched == 1 and prf.f1 == 1.0
+
+
+def test_entity_type_mismatch_blocks_match():
+    g = [{"name": "Apple", "type": "org"}]
+    p = [{"name": "Apple", "type": "person"}]
+    assert ed.diff_axis(g, p, "entities").matched == 0
+
+
+def test_entity_other_type_is_compatible():
+    g = [{"name": "Apple", "type": "org"}]
+    p = [{"name": "Apple", "type": "other"}]
+    assert ed.diff_axis(g, p, "entities").matched == 1
+
+
+def test_entity_greedy_one_to_one():
+    # two golds, one pred → at most one match
+    g = [{"name": "Acme", "type": "org"}, {"name": "Acme", "type": "org"}]
+    p = [{"name": "Acme", "type": "org"}]
+    prf = ed.diff_axis(g, p, "entities")
+    assert prf.matched == 1 and prf.recall == 0.5 and prf.precision == 1.0
+
+
+# ── fact matching (structural vs statement) ──────────────────────────────
+
+def test_fact_match_on_structure_despite_statement_rephrase():
+    g = [{"category": "decision", "subject": "Acme", "predicate": "will renew",
+          "object": "the contract", "statement": "Acme decided to renew the contract for 2027."}]
+    p = [{"category": "decision", "subject": "Acme", "predicate": "renews",
+          "object": "contract", "statement": "The 2027 contract renewal was agreed by Acme."}]
+    prf = ed.diff_axis(g, p, "facts")
+    assert prf.matched == 1
+
+
+def test_fact_match_on_statement_when_spo_split_differs():
+    g = [{"category": "commitment", "subject": "Bob", "predicate": "owns", "object": "migration",
+          "statement": "Bob will lead the migration starting in March."}]
+    p = [{"category": "commitment", "subject": "Bob Chen", "predicate": "leads",
+          "object": "the data migration", "statement": "Bob will lead the migration starting in March."}]
+    assert ed.diff_axis(g, p, "facts").matched == 1
+
+
+def test_fact_unrelated_no_match():
+    g = [{"category": "decision", "subject": "Acme", "predicate": "hired", "object": "a CFO",
+          "statement": "Acme hired a new CFO."}]
+    p = [{"category": "decision", "subject": "Globex", "predicate": "closed", "object": "the Berlin office",
+          "statement": "Globex shut its Berlin office."}]
+    assert ed.diff_axis(g, p, "facts").matched == 0
+
+
+# ── relationships ────────────────────────────────────────────────────────
+
+def test_relationship_triple_match():
+    g = [{"from": "Jane", "to": "Acme Corp", "type": "works at"}]
+    p = [{"from": "Jane", "to": "Acme", "type": "employed by"}]
+    # from + to match strongly; type weaker → mean may dip below threshold
+    prf = ed.diff_axis(g, p, "relationships")
+    assert prf.n_gold == 1 and prf.n_pred == 1
+
+
+# ── full diff + per-category + filtered ──────────────────────────────────
+
+def test_diff_extractions_per_category_and_filtered():
+    gold = {
+        "entities": [{"name": "Acme", "type": "org"}],
+        "facts": [
+            {"category": "decision", "subject": "Acme", "predicate": "will renew",
+             "object": "contract", "statement": "Acme will renew the contract."},
+            {"category": "state", "subject": "Acme", "predicate": "is", "object": "a customer",
+             "statement": "Acme is a customer."},
+        ],
+        "relationships": [],
+    }
+    pred = {
+        "entities": [{"name": "Acme Corp", "type": "org"}],
+        "facts": [
+            {"category": "decision", "subject": "Acme", "predicate": "renews",
+             "object": "the contract", "statement": "Acme renews its contract."},
+        ],
+        "relationships": [],
+    }
+    out = ed.diff_extractions(gold, pred, fact_categories={"decision", "commitment"})
+    assert out["entities"]["matched"] == 1
+    # per-category: decision matched 1/1; state missing (recall 0)
+    assert out["facts_by_category"]["decision"]["matched"] == 1
+    assert out["facts_by_category"]["state"]["recall"] == 0.0
+    # filtered to decision/commitment: 1 gold, 1 pred, 1 matched → perfect
+    assert out["facts_filtered"]["recall"] == 1.0
+    assert out["facts_filtered"]["precision"] == 1.0
+    assert out["facts_filtered_categories"] == ["commitment", "decision"]
+
+
+def test_diff_extractions_empty_both():
+    out = ed.diff_extractions({"entities": [], "facts": [], "relationships": []},
+                              {"entities": [], "facts": [], "relationships": []})
+    assert out["facts"]["f1"] == 1.0

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

@@ -0,0 +1,58 @@
+"""Guard tests for the distiller system-prompt content rules.
+
+Pins that the email-discipline + entity-separation rules (this change) and the
+#126 modality/attribution rules are present in BOTH prompt variants — a cheap
+regression guard so a future prompt edit can't silently drop them.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+_THIS = Path(__file__).resolve().parent
+
+
+def _load(name="extractor_async_worker_prompts"):
+    spec = importlib.util.spec_from_file_location(name, _THIS / "worker.py")
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+try:
+    worker = _load()
+except ImportError as e:
+    pytest.skip(f"extractor-async deps unavailable: {e}", allow_module_level=True)
+
+PROMPTS = lambda: (worker.BATCH_SYSTEM_PROMPT, worker.GUIDED_JSON_SYSTEM_PROMPT)
+
+
+def test_email_discipline_in_both_prompts():
+    for p in PROMPTS():
+        assert "An email address is NOT a person" in p
+        assert "reservations@" in p           # role/transactional examples present
+        assert "clearly THEIRS" in p           # bystander-attachment ban
+
+
+def test_distinct_entities_rule_in_both_prompts():
+    for p in PROMPTS():
+        assert "DISTINCT ENTITIES" in p
+        assert "Acme & Globex" in p            # conflation-split example
+        assert "warehouse" in p                # generic-token suppression
+
+
+def test_126_rules_not_regressed():
+    for p in PROMPTS():
+        assert "TENSE & MODALITY" in p
+        assert "ATTRIBUTION FIDELITY" in p
+
+
+def test_active_prompt_carries_the_rules_and_fresh_hash():
+    assert "An email address is NOT a person" in worker.ACTIVE_SYSTEM_PROMPT
+    assert "DISTINCT ENTITIES" in worker.ACTIVE_SYSTEM_PROMPT
+    assert len(worker.SYSTEM_PROMPT_HASH) == 16  # hash recomputed off ACTIVE prompt

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

@@ -284,6 +284,38 @@ and NEVER drop a field.
   object MAY be an entity name OR a literal string OR `-` if absent.
   statement ≤ 140 characters, a self-contained sentence.
   WORKED EXAMPLE: `FCT|commitment|Timothy Bradley|agreed to|SAFE amendments|Timothy confirmed the SAFE amendments are set (14 May 2026)`
+- TENSE & MODALITY — never record the future or the merely-planned as done:
+  * A SCHEDULED or FUTURE event (a calendar invite, a meeting/call dated \
+later than this event, a recurring-meeting instance) is UPCOMING, not \
+completed. NEVER emit "attended / hosted / met / reported / decided" for a \
+meeting that has not happened — use category=commitment with predicate "is \
+scheduled to" / "plans to".
+  * A PLAN, PROPOSAL, INTENT or next-step ("will", "plans to", "aims to", \
+"to organise", "we'll", "next steps:") is category=commitment, NOT state and \
+NOT a completed act. Keep "will send" as a commitment — never record it as "sent".
+- ATTRIBUTION FIDELITY — the subject must be who the source actually credits:
+  * Attribute a document/deck/message's content to a person ONLY if the source \
+names them as its author or speaker. Do NOT attribute an unauthored doc, agenda \
+or deck to whoever it merely mentions or whoever shared it.
+  * Do NOT promote a meeting ATTENDEE to organiser/host without explicit evidence.
+  * Do NOT attribute an ORGANISATION's activity (deals, intros, pipeline) to an \
+individual person.
+- IDENTITY & EMAILS — do NOT infer a person's employer/affiliation from an email \
+signature or a company's standard footer/boilerplate; affiliation needs an \
+explicit statement in the body. \
+An email address is NOT a person: NEVER emit an entity whose name is an email \
+address, and NEVER treat a role/transactional address (reservations@, bookings@, \
+no-reply@, info@, office@, marketing@, support@, notifications@, admin@) as a \
+person. Attach an email to a person ONLY when it is clearly THEIRS (the author, \
+or a local-part matching their name) — NEVER attach an address that merely \
+co-occurs in the same thread, CC list, or document (a hotel booking, a \
+newsletter, an unrelated contact).
+- DISTINCT ENTITIES — two names joined by "and" / "&" / "/" are TWO separate \
+entities, never one merged node ("Acme & Globex" → emit Acme AND Globex). Do NOT \
+turn a sentence fragment or phrase into an entity, and do NOT mint generic \
+infrastructure / environment tokens (prod, staging, preview, UAT, warehouse, \
+main, PRD, CRM, platform, localhost) as entities — they are not named people, \
+orgs, products, or projects.
 - REL lines have exactly 4 fields: `REL`, from, to, rel_type.
   from and to MUST be entity names declared in THIS event's ENT lines.
   rel_type is a short verb / preposition phrase.
@@ -337,6 +369,38 @@ observation, preference}.
   WORKED EXAMPLE: {"category": "commitment", "subject": "Timothy \
 Bradley", "predicate": "agreed to", "object": "SAFE amendments", \
 "statement": "Timothy confirmed the SAFE amendments are set (14 May 2026)"}
+- TENSE & MODALITY — never record the future or the merely-planned as done:
+  * A SCHEDULED or FUTURE event (a calendar invite, a meeting/call dated \
+later than this event, a recurring-meeting instance) is UPCOMING, not \
+completed. NEVER emit "attended / hosted / met / reported / decided" for a \
+meeting that has not happened — use category=commitment with predicate "is \
+scheduled to" / "plans to".
+  * A PLAN, PROPOSAL, INTENT or next-step ("will", "plans to", "aims to", \
+"to organise", "we'll", "next steps:") is category=commitment, NOT state and \
+NOT a completed act. Keep "will send" as a commitment — never record it as "sent".
+- ATTRIBUTION FIDELITY — the subject must be who the source actually credits:
+  * Attribute a document/deck/message's content to a person ONLY if the source \
+names them as its author or speaker. Do NOT attribute an unauthored doc, agenda \
+or deck to whoever it merely mentions or whoever shared it.
+  * Do NOT promote a meeting ATTENDEE to organiser/host without explicit evidence.
+  * Do NOT attribute an ORGANISATION's activity (deals, intros, pipeline) to an \
+individual person.
+- IDENTITY & EMAILS — do NOT infer a person's employer/affiliation from an email \
+signature or a company's standard footer/boilerplate; affiliation needs an \
+explicit statement in the body. \
+An email address is NOT a person: NEVER emit an entity whose name is an email \
+address, and NEVER treat a role/transactional address (reservations@, bookings@, \
+no-reply@, info@, office@, marketing@, support@, notifications@, admin@) as a \
+person. Attach an email to a person ONLY when it is clearly THEIRS (the author, \
+or a local-part matching their name) — NEVER attach an address that merely \
+co-occurs in the same thread, CC list, or document (a hotel booking, a \
+newsletter, an unrelated contact).
+- DISTINCT ENTITIES — two names joined by "and" / "&" / "/" are TWO separate \
+entities, never one merged node ("Acme & Globex" → emit Acme AND Globex). Do NOT \
+turn a sentence fragment or phrase into an entity, and do NOT mint generic \
+infrastructure / environment tokens (prod, staging, preview, UAT, warehouse, \
+main, PRD, CRM, platform, localhost) as entities — they are not named people, \
+orgs, products, or projects.
 - relationships: "from" and "to" MUST be entity names declared in THIS \
 event's "entities". "type" is a short verb / preposition phrase.
 - HARD CAPS per event: 8 entities, 6 facts, 6 relationships. Pick the \
@@ -1189,6 +1253,43 @@ def org_node_id_key(entity_type: str, name: str, stamped_domain: str | None) ->
     return name
 
 
+# --------------------------------------------------------------------
+# Email-alias guard — stop bystander emails polluting a person
+# --------------------------------------------------------------------
+# The async LLM pass sometimes emits a PERSON entity whose `email` is a BYSTANDER
+# address co-occurring in the same doc/thread (a hotel booking, a newsletter, an
+# unrelated gmail). _parse_guided_json promotes it into the entity's aliases and
+# upsert_entities then stores + RESOLVES on it — folding strangers' identities
+# (and their facts) onto the person. Measured live (pentatonic-team): a "Johann
+# Boedecker" node carrying reservations.nyc@acehotel.com + unrelated gmails, all
+# from STUDENT-distilled `doc` events. This guard keeps an email alias on a person
+# only when its local-part plausibly relates to the person's name; clear bystanders
+# are dropped BEFORE resolution/storage. Conservative: dropping a genuine but
+# non-name-matching alias is a mild loss; keeping a bystander is a confabulation
+# source. Flag-revertible (EMAIL_ALIAS_GUARD=false). Persons only — org domain
+# stamping is untouched.
+EMAIL_ALIAS_GUARD = _envflag("EMAIL_ALIAS_GUARD", "true")
+_ALIAS_NONALPHA = re.compile(r"[^a-z]")
+_ALIAS_SPLIT = re.compile(r"[^a-z]+")
+
+
+def _email_plausibly_belongs(person_name: str, email: str) -> bool:
+    """True ⇒ keep this email as an alias of `person_name`; False ⇒ drop (clear
+    bystander). Match = a name token appears in the local-part, OR the local-part
+    is the person's initials. Pure + deterministic."""
+    local = email.split("@", 1)[0].lower()
+    local_letters = _ALIAS_NONALPHA.sub("", local)
+    name_tokens = {t for t in _ALIAS_SPLIT.split(person_name.lower()) if len(t) >= 2}
+    if not name_tokens or not local_letters:
+        return True  # nothing to check against — don't over-filter
+    if any(nt in local_letters for nt in name_tokens):
+        return True  # johann@…, johann.boedecker@…, boedeckerjohann@…
+    initials = "".join(t[0] for t in person_name.lower().split() if t[:1].isalpha())
+    if len(initials) >= 2 and local_letters in (initials, initials[::-1]):
+        return True  # jb@… / bj@… for "Johann Boedecker"
+    return False
+
+
 def upsert_entities(
     conn: psycopg.Connection,
     arena: str,
@@ -1281,6 +1382,21 @@ def upsert_entities(
                 continue
             aliases = [a for a in (e.get("aliases") or []) if a]
 
+            # Email-alias guard (persons only): drop bystander emails the LLM
+            # stapled on from a co-occurring doc/thread, BEFORE they reach
+            # resolution or storage. See _email_plausibly_belongs.
+            if EMAIL_ALIAS_GUARD and etype == "person" and aliases:
+                kept = []
+                for a in aliases:
+                    if "@" in a and " " not in a and not _email_plausibly_belongs(name, a):
+                        log.info(
+                            f"alias-guard: dropped bystander email {a!r} from "
+                            f"person {name!r} (arena={arena})"
+                        )
+                        continue
+                    kept.append(a)
+                aliases = kept
+
             # 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