secondbrain-py 0.2.1__py3-none-any.whl

brain/vault/derived_links/fence.py

@@ -0,0 +1,408 @@
+"""Fenced auto-section for derived edges in `_ingested/` bodies.
+
+Each ingested-tier vault file gets a single trailing section, bracketed by
+HTML-comment markers, that materializes the document's metadata-derived
+partners as native Obsidian/Quartz wiki-links so they're visible in
+Quartz's `/graph` view (see
+``docs/specs/2026-04-30-derived-edges-in-bodies-design.md``).
+
+The fence is what keeps this safe across the rest of the pipeline:
+
+- Sync's ``body_hash`` strips the fence before hashing → freshly-rendered
+  fences don't trigger the re-embed cascade.
+- Sync's normalized-body-for-DB strips the fence → ``documents.content``
+  stays clean, so vector search isn't polluted by "Related" lists.
+- Wiki-link parser skips the fence → ``[[stems]]`` inside the fence don't
+  double-count edges that already live in ``derived_links``.
+
+This module ships:
+
+- Pure-string helpers: :func:`extract_fence`, :func:`strip_fence`,
+  :func:`replace_fence`. No DB.
+- DB-reading renderer: :func:`render_fenced_section` — produces the
+  fenced markdown for a doc id from current ``derived_links`` rows.
+- File-rewriting renderer: :func:`rewrite_derived_fences` — for each
+  affected ingested-tier doc, regenerates the fence on disk via an
+  atomic write. Skips vault-tier docs (Q3=a) and docs without an
+  ``_ingested/`` mirror (covered by export, not the fence renderer).
+"""
+import datetime
+import logging
+from email.utils import parsedate_to_datetime
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+import psycopg
+import yaml
+
+from .._atomic import atomic_write_text
+from ..paths import safe_wikilink_alias
+
+# Stable HTML-comment markers. Universal CommonMark — Obsidian, Quartz, GFM,
+# and standard Markdown all treat the line as a passthrough HTML comment.
+# Public so the sync engine and watcher can detect fence regions without
+# re-importing internal regex state.
+FENCE_START_MARKER: str = "<!-- BRAIN_DERIVED_START -->"
+FENCE_END_MARKER: str = "<!-- BRAIN_DERIVED_END -->"
+
+# Rules surfaced in the Quartz-visible fence. ``shared_participant`` (R2) is
+# excluded because it's high-recall / low-precision: at corpus scale it
+# produces an N×N hairball that breaks Quartz's force-directed graph layout
+# (the user is a participant in nearly every doc, so almost every doc shares
+# a participant with almost every other doc). R2 edges remain queryable via
+# ``brain backlinks`` / ``brain graph`` / MCP — only the Quartz surface is
+# narrowed, not the underlying ``derived_links`` table.
+#
+# Sorted to give psycopg a stable parameter binding shape.
+FENCE_RULES: tuple[str, ...] = ("same_day_participant", "shared_thread")
+
+# Section heading inside the fence. Stable so users (and `git diff`) can grep
+# for it.
+_SECTION_HEADING: str = "## Related (auto-generated, do not edit)"
+
+_logger = logging.getLogger(__name__)
+
+
+
+def extract_fence(body: str) -> tuple[str, str | None]:
+    """Split ``body`` into ``(body_without_fence, fence_text_or_None)``.
+
+    The returned ``fence_text`` includes the start/end markers; the body
+    slice excludes the entire fence region (markers + everything between).
+
+    If multiple ``BRAIN_DERIVED_START`` markers appear in the body
+    (corruption — e.g. two stacked fences from a buggy renderer), only
+    the first is treated as the fence anchor; later markers stay in
+    ``body_without_fence`` as plain text. Recovery is then a re-render
+    away.
+
+    Bodies without a fence return ``(body, None)`` unchanged.
+    """
+    start_idx = body.find(FENCE_START_MARKER)
+    if start_idx == -1:
+        return body, None
+
+    # Search for the matching END marker AFTER the START. A stray END before
+    # the first START is treated as content (no fence detected — earlier
+    # ``find`` returned -1 — so we never reach this branch in that case).
+    end_search_from = start_idx + len(FENCE_START_MARKER)
+    end_idx = body.find(FENCE_END_MARKER, end_search_from)
+    if end_idx == -1:
+        # START with no matching END — treat as malformed and leave body
+        # untouched so the user sees the corruption rather than us silently
+        # eating the rest of the file.
+        return body, None
+
+    fence_close = end_idx + len(FENCE_END_MARKER)
+    fence_text = body[start_idx:fence_close]
+    body_without = body[:start_idx] + body[fence_close:]
+    return body_without, fence_text
+
+
+def strip_fence(body: str) -> str:
+    """Return ``body`` with the fenced region removed.
+
+    Idempotent — calling on a body that has no fence returns it unchanged,
+    so ``strip_fence(strip_fence(x)) == strip_fence(x)``. This is what the
+    sync engine uses to compute a fence-stable ``body_hash`` (and a
+    fence-free ``documents.content`` projection).
+
+    When a fence is removed, trailing whitespace it introduced (the blank
+    line that separated user content from the fence, plus any newline
+    after the END marker) is collapsed and replaced with a single trailing
+    ``\\n``. Two fenced bodies that only differ in their fence content
+    therefore strip to byte-identical strings — that's the property the
+    ``body_hash`` strip relies on to avoid re-embed loops.
+
+    Bodies without a fence are returned unchanged so the function is a
+    pure no-op for files the renderer has never touched.
+    """
+    body_without, fence = extract_fence(body)
+    if fence is None:
+        return body
+    trimmed = body_without.rstrip()
+    return trimmed + "\n" if trimmed else ""
+
+
+def replace_fence(body: str, new_fence: str) -> str:
+    """Return ``body`` with its fence swapped for ``new_fence`` (appending if absent).
+
+    ``new_fence`` is the fully-rendered fenced section — including the
+    start/end markers — typically produced by :func:`render_fenced_section`.
+    The function strips any pre-existing fence first, then appends
+    ``new_fence`` after exactly one blank-line separator and finishes with a
+    single trailing newline.
+
+    Edge cases handled:
+
+    - Body without trailing newline → fence appended cleanly with separator.
+    - Body with one or more trailing newlines → trailing whitespace is
+      normalized so the result ends with exactly one ``\\n`` after the END
+      marker (no double-blank, no missing-newline).
+    - Body already containing a fence → that fence is removed before the
+      new one is appended (so callers can pass the renderer's latest output
+      directly without manual orchestration).
+    """
+    base, _existing = extract_fence(body)
+    base = base.rstrip()
+    if not base:
+        return new_fence + "\n"
+    return f"{base}\n\n{new_fence}\n"
+
+
+def render_fenced_section(
+    conn: psycopg.Connection[Any], doc_id: str
+) -> str | None:
+    """Build the fenced section for ``doc_id`` from the current ``derived_links``.
+
+    Queries every derived edge whose ``src`` or ``dst`` is ``doc_id`` AND
+    whose ``rule`` is in :data:`FENCE_RULES` (i.e. R1/R3 — ``shared_thread``
+    and ``same_day_participant``). R2 (``shared_participant``) is filtered
+    out at the SQL layer because it's high-recall / low-precision and at
+    corpus scale produces a graph hairball that breaks Quartz's
+    force-directed layout. R2 edges remain queryable via every other read
+    surface (``brain backlinks`` / ``brain graph`` / MCP); only the
+    Quartz-visible fence is narrowed.
+
+    Joins ``documents`` for each partner's title / vault_path / metadata
+    and emits one bullet per edge:
+
+        - [[<partner-filename-stem>|<partner-title>]] *(<rule>)*
+
+    Sort order (deterministic, primary→tertiary):
+
+    1. ``rule weight DESC`` — highest-weight rules surface first (R1
+       ``shared_thread`` weight 1.0 before R3 ``same_day_participant``
+       weight 0.7).
+    2. Partner ``metadata->>'date'`` DESC — within a weight tier, newer
+       partners win. Partners with a missing or unparseable date sort
+       AFTER partners with a date.
+    3. Partner document ``id`` ASC — final tie-breaker so two partners
+       with identical weight + identical date (or both undated) always
+       emit in the same order across runs. Without this every relink →
+       sync round-trip risked reshuffling the bullet list and bumping
+       file mtimes unnecessarily.
+
+    Both the SQL query and the in-memory sort are stable: SQL
+    ``ORDER BY`` pins the row delivery order, and Python's ``list.sort``
+    is guaranteed stable, so the tertiary id key dominates only when the
+    weight + date keys tie.
+
+    Partners without a ``vault_path`` (not exported yet) are skipped — the
+    wiki-link wouldn't resolve in Quartz anyway. If skipping leaves the
+    bullet list empty (or the rule filter dropped every edge for this
+    doc), returns ``None`` (caller should remove the fence rather than
+    emit an empty section).
+    """
+    rows = conn.execute(
+        """
+        SELECT
+            partner.id::text,
+            partner.title,
+            partner.vault_path,
+            partner.metadata,
+            dl.rule,
+            dl.weight
+        FROM derived_links dl
+        JOIN documents partner ON partner.id = (
+            CASE WHEN dl.src_document_id = %s::uuid
+                 THEN dl.dst_document_id
+                 ELSE dl.src_document_id
+            END
+        )
+        WHERE (dl.src_document_id = %s::uuid
+               OR dl.dst_document_id = %s::uuid)
+          AND dl.rule = ANY(%s)
+        ORDER BY dl.weight DESC,
+                 partner.metadata->>'date' DESC NULLS LAST,
+                 partner.id ASC
+        """,
+        (doc_id, doc_id, doc_id, list(FENCE_RULES)),
+    ).fetchall()
+
+    bullets: list[tuple[float, bool, int, str, str]] = []
+    # Sort key tuple meaning:
+    #   index 0: -weight  → ascending sort puts highest weight first
+    #   index 1: date_missing (False<True) → with-date partners first within tier
+    #   index 2: -date.toordinal() → ascending puts newest date first
+    #   index 3: partner_id ASC → deterministic tertiary tie-breaker so
+    #            partners with identical weight + identical date emit in
+    #            the same order across runs (no mtime churn from
+    #            relink → sync cycles re-shuffling tied bullets).
+    for partner_id, title, vault_path, metadata, rule, weight in rows:
+        if not vault_path:
+            _logger.debug(
+                "fence: skipping partner %s (no vault_path yet)", partner_id
+            )
+            continue
+        stem = PurePosixPath(str(vault_path)).stem
+        partner_date = _parse_metadata_date(dict(metadata or {}))
+        date_missing = partner_date is None
+        date_key = -partner_date.toordinal() if partner_date else 0
+        bullet = f"- [[{stem}|{safe_wikilink_alias(title)}]] *({rule})*"
+        bullets.append(
+            (-float(weight), date_missing, date_key, str(partner_id), bullet)
+        )
+
+    if not bullets:
+        return None
+
+    bullets.sort(key=lambda b: (b[0], b[1], b[2], b[3]))
+    body_lines = [FENCE_START_MARKER, _SECTION_HEADING]
+    body_lines.extend(b[4] for b in bullets)
+    body_lines.append(FENCE_END_MARKER)
+    return "\n".join(body_lines)
+
+
+def _parse_metadata_date(metadata: dict[str, Any]) -> datetime.date | None:
+    """Best-effort parse of ``metadata['date']`` into a :class:`datetime.date`.
+
+    Mirrors the shapes ``brain.vault.derived_links.pass_runner._parse_date``
+    accepts (ISO ``YYYY-MM-DD`` for Krisp, RFC 5322 for Gmail) but doesn't
+    require knowing the source kind — the renderer is sort-only and tolerant
+    of either form. Returns ``None`` for missing, non-string, or
+    unparseable values; partners with a missing date sort last within the
+    same weight tier.
+    """
+    raw = metadata.get("date")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    if not text:
+        return None
+
+    # Try ISO YYYY-MM-DD first (Krisp). Slicing tolerates "YYYY-MM-DDTHH:MM"
+    # without pulling in the wider ``datetime.fromisoformat`` grammar.
+    try:
+        return datetime.date.fromisoformat(text[:10])
+    except ValueError:
+        pass
+
+    # Fall back to RFC 5322 (Gmail).
+    try:
+        parsed = parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    if parsed is None:
+        return None
+    return parsed.date()
+
+
+def rewrite_derived_fences(
+    conn: psycopg.Connection[Any],
+    doc_ids: set[str],
+    *,
+    vault_path: Path,
+) -> int:
+    """Regenerate the derived-edges fence for every affected ``_ingested/`` file.
+
+    Driven by ``rebuild_derived_for``'s ``affected_ids`` return value:
+    every doc whose edges changed (gained or lost) gets its fence rewritten
+    on disk, so Quartz's ``/graph`` view stays consistent with the latest
+    ``derived_links`` rows.
+
+    Behavior per the user's Q3–Q5 decisions (with the 2026-05-08 idempotency fix):
+
+    - **Q3=a** vault-tier files are silently skipped — user-authored notes
+      stay untouched in v1. Only docs with ``kind='ingested'`` are
+      candidates.
+    - **Skip on byte-identical** (supersedes the original Q4=b "always
+      rewrite"): if the freshly-rendered file text is byte-identical to
+      what's already on disk, the file is NOT written and is NOT counted.
+      The returned ``written`` count reflects actual disk writes, so
+      ``relink-derived → sync`` is a true no-op for unchanged docs (no
+      mtime bumps, no Quartz rebuild churn) and the caller's reported
+      counter cannot lie about disk effect.
+    - **Q5=b** + Q2a fence content uses ``[[<filename-stem>|<title>]]
+      *(<rule>)*`` (rendered by :func:`render_fenced_section`).
+
+    Returns the count of files actually written. Docs in ``doc_ids`` that
+    map to a vault-tier row, have no ``vault_path`` set, whose mirror
+    file is missing on disk, OR whose freshly-rendered text matches the
+    on-disk text byte-for-byte are silently dropped from the count —
+    those skips aren't failures, they're "the renderer has no work to do
+    here."
+
+    Atomicity: each write goes through a sibling temp file plus
+    :func:`os.replace`, which is atomic on POSIX (rename(2)). A crash
+    mid-write leaves the original file intact; the temp file is cleaned
+    up on the next pass over the same doc id.
+
+    Empty input short-circuits to ``0`` — no DB round-trip, no FS scan.
+    """
+    if not doc_ids:
+        return 0
+
+    # Local imports break a cycle: ``brain.vault.frontmatter`` imports
+    # :func:`strip_fence` from this module so its ``body_hash`` ignores the
+    # fence content; we in turn need its parse/dump helpers to round-trip
+    # the YAML frontmatter while editing the body. Lazy-loading at call
+    # time keeps both modules' top-level imports cycle-free.
+    from ..frontmatter import dump_frontmatter, parse_frontmatter
+
+    # Single batch lookup: kind + vault_path for every affected doc id. At
+    # production scale (~500 ingested docs) the IN-list fits comfortably in
+    # one query and saves N round-trips on a full corpus relink.
+    rows = conn.execute(
+        "SELECT id::text, kind, vault_path FROM documents "
+        "WHERE id = ANY(%s)",
+        (sorted(doc_ids),),
+    ).fetchall()
+
+    written = 0
+    for doc_id, kind, vp in rows:
+        # Q3=a: vault-tier files stay untouched in v1.
+        if kind != "ingested":
+            continue
+        # No mirror exported yet — the fence renderer has no file to
+        # rewrite. Export will produce one on the next pass; this is not
+        # an error.
+        if not vp:
+            continue
+        target = vault_path / str(vp)
+        if not target.is_file():
+            _logger.debug(
+                "fence: skipping %s — vault_path %r has no file on disk",
+                doc_id, vp,
+            )
+            continue
+        try:
+            text = target.read_text(encoding="utf-8")
+        except OSError as e:
+            _logger.warning(
+                "fence: could not read %s: %s — skipping", target, e
+            )
+            continue
+        try:
+            frontmatter, body = parse_frontmatter(text)
+        except (ValueError, yaml.YAMLError) as e:
+            _logger.warning(
+                "fence: malformed frontmatter in %s: %s — skipping",
+                target, e,
+            )
+            continue
+
+        new_fence = render_fenced_section(conn, doc_id)
+        new_body = (
+            strip_fence(body) if new_fence is None
+            else replace_fence(body, new_fence)
+        )
+        new_text = dump_frontmatter(frontmatter, new_body)
+
+        # Idempotency: skip the write entirely when the rendered text is
+        # byte-identical to what's already on disk. This is the contract
+        # that lets ``relink-derived → sync`` round-trip without bumping
+        # mtimes — counters reflect real disk effect, not "we ran the
+        # renderer."  See ``docs/plans/2026-05-08-vault-sync-fence-strip-bug.md``.
+        if new_text == text:
+            continue
+
+        try:
+            atomic_write_text(target, new_text)
+        except OSError as e:
+            _logger.warning(
+                "fence: could not rewrite %s: %s — skipping", target, e
+            )
+            continue
+        written += 1
+    return written

brain/vault/derived_links/gws.py

@@ -0,0 +1,64 @@
+"""Production ``gws`` subprocess runner conforming to the GwsRunner Protocol.
+
+Mirrors the shell-out shape used by ``brain.ingest.gmail._run`` but routes
+all expected subprocess failures (missing binary, non-zero exit, timeout,
+unexpected ``OSError``) through :class:`brain.errors.DirectoryRefreshError`
+so the refresh helpers in ``directory.py`` can downgrade them to soft
+warnings (``refresh_calendar`` / ``refresh_contacts`` already catch
+``DirectoryRefreshError`` from the runner).
+
+CLAUDE.md security rules: explicit timeout (30s), narrow exception catch,
+no ``shell=True``, output truncation in error messages so logs stay
+readable when ``gws`` chatters on stderr.
+"""
+import shutil
+import subprocess
+
+from brain.errors import DirectoryRefreshError
+
+# Hard cap on stderr included in the translated error message — keeps logs
+# readable when ``gws`` panics with a long Python traceback.
+_STDERR_SNIPPET_LIMIT = 200
+
+# Default subprocess timeout. ``gws`` calendar / people calls are I/O bound
+# against Google APIs; 30s is generous for a single page.
+_DEFAULT_TIMEOUT_SECONDS = 30
+
+
+def real_gws_runner(args: list[str]) -> str:
+    """Shell out to the ``gws`` CLI; return stdout, translate failures.
+
+    Translates ``FileNotFoundError`` (gws missing), ``CalledProcessError``
+    (non-zero exit), ``TimeoutExpired`` (timeout), and any other
+    ``OSError`` into :class:`DirectoryRefreshError` so the refresh helpers
+    in ``directory.py`` log them as warnings and return 0.
+
+    Conforms to the :class:`brain.vault.derived_links.directory.GwsRunner`
+    Protocol so it can be passed straight into
+    ``refresh_calendar`` / ``refresh_contacts``.
+    """
+    if not args:
+        raise DirectoryRefreshError("gws runner invoked with empty args")
+    if not shutil.which(args[0]):
+        raise DirectoryRefreshError(f"`{args[0]}` CLI not found on PATH")
+    try:
+        proc = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=_DEFAULT_TIMEOUT_SECONDS,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr_snippet = (exc.stderr or "").strip()[:_STDERR_SNIPPET_LIMIT]
+        raise DirectoryRefreshError(
+            f"gws command failed (exit {exc.returncode}): {stderr_snippet}"
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise DirectoryRefreshError(
+            f"gws command timed out after {_DEFAULT_TIMEOUT_SECONDS}s: "
+            f"{' '.join(args)}"
+        ) from exc
+    except OSError as exc:
+        raise DirectoryRefreshError(f"gws command failed: {exc}") from exc
+    return proc.stdout

brain/vault/derived_links/participants.py

@@ -0,0 +1,143 @@
+"""Pure participant-extraction helpers — Krisp speaker labels + Gmail headers."""
+import re
+from email.utils import getaddresses
+from typing import Any
+
+# Krisp writes unidentified speakers as ``Speaker <digits>`` (real transcripts,
+# space separator) or ``Speaker_<digits>`` (legacy / synthetic test data,
+# underscore). Either form is dropped because it would over-link unrelated
+# calls — every transcript starts numbering at 1, so ``Speaker 2`` from one
+# call has nothing to do with ``Speaker 2`` from another.
+_SPEAKER_PLACEHOLDER_RE = re.compile(r"^speaker[ _]\d+$")
+
+# Krisp inline speaker label: ``**<name-or-email> | mm:ss**`` (or ``H:MM:SS``
+# for calls over an hour). Capture the label text only. The optional
+# ``(?:\d{1,2}:)?`` head allows the H prefix without forcing it.
+_KRISP_SPEAKER_RE = re.compile(
+    r"\*\*([^|*]+?)\s*\|\s*(?:\d{1,2}:)?\d{1,2}:\d{2}\s*\*\*",
+)
+
+# Internal-whitespace collapse used by name normalization.
+_WHITESPACE_RE = re.compile(r"\s+")
+
+# Single-letter "names" (A, J) are too noisy to link on; require at least two
+# characters after normalization.
+_MIN_NAME_LENGTH = 2
+
+
+def is_email_like(addr: str) -> bool:
+    """Heuristic: exactly one ``@``, both halves non-empty, RHS has a ``.``, no whitespace."""
+    if any(ch.isspace() for ch in addr):
+        return False
+    if addr.count("@") != 1:
+        return False
+    local, _, domain = addr.partition("@")
+    if not local or not domain:
+        return False
+    return "." in domain
+
+
+def _normalize_email(addr: str) -> str | None:
+    """Strip surrounding angle brackets + whitespace, lowercase, validate.
+
+    Brackets are stripped independently — a token with only a leading ``<`` or
+    only a trailing ``>`` still has the stray bracket removed before
+    validation. ``is_email_like`` is the final gate.
+    """
+    cleaned = addr.strip().lower()
+    if cleaned.startswith("<"):
+        cleaned = cleaned[1:]
+    if cleaned.endswith(">"):
+        cleaned = cleaned[:-1]
+    cleaned = cleaned.strip()
+    if not is_email_like(cleaned):
+        return None
+    return cleaned
+
+
+def normalize_participant(token: str) -> str | None:
+    """Lowercase + strip; return email if `@` present, normalized name otherwise.
+
+    Returns None for empty / Speaker_N / clearly-malformed tokens.
+    """
+    stripped = token.strip()
+    if not stripped:
+        return None
+
+    # Drop unidentified Krisp speakers (case-insensitive).
+    if _SPEAKER_PLACEHOLDER_RE.match(stripped.lower()):
+        return None
+
+    # Email branch: any token containing ``@`` is treated as email.
+    if "@" in stripped:
+        return _normalize_email(stripped)
+
+    # Name branch: lowercase, collapse whitespace, strip outer punctuation.
+    lowered = stripped.lower()
+    collapsed = _WHITESPACE_RE.sub(" ", lowered)
+    # Strip leading/trailing punctuation (anything that's not alphanumeric or
+    # an internal space). We re-strip whitespace afterwards because removing
+    # punctuation can leave dangling spaces (``", Pat."`` → ``" pat "``).
+    name = collapsed.strip(" \t\n\r\f\v.,;:!?\"'()[]{}<>-_/\\|")
+    name = name.strip()
+    if len(name) < _MIN_NAME_LENGTH:
+        return None
+    return name
+
+
+def extract_krisp_speakers(body: str) -> set[str]:
+    """Parse `**name-or-email | mm:ss**` labels from a Krisp transcript body.
+
+    Drops Speaker_N placeholders. Returns the set of normalized participant
+    keys (emails preferred, names where no email is present).
+    """
+    if not body:
+        return set()
+
+    speakers: set[str] = set()
+    for match in _KRISP_SPEAKER_RE.finditer(body):
+        normalized = normalize_participant(match.group(1))
+        if normalized is not None:
+            speakers.add(normalized)
+    return speakers
+
+
+def extract_gmail_addresses(metadata: dict[str, Any]) -> list[tuple[str | None, str]]:
+    """Use `email.utils.getaddresses` over metadata['from'] + metadata['to'].
+
+    Returns list of (display_name, email) tuples. display_name is None when
+    absent. Both elements are normalized (lowercased, stripped). Display
+    names are run through `normalize_participant` for cross-source matching
+    consistency — that drops outer punctuation and rejects sub-2-char or
+    Speaker_N values that would never resolve through the directory anyway.
+    """
+    raw_strings: list[str] = []
+    for key in ("from", "to"):
+        value = metadata.get(key)
+        if isinstance(value, str) and value.strip():
+            raw_strings.append(value)
+
+    if not raw_strings:
+        return []
+
+    seen_emails: set[str] = set()
+    pairs: list[tuple[str | None, str]] = []
+    for realname, addr in getaddresses(raw_strings):
+        email = (addr or "").strip().lower()
+        if not email or not is_email_like(email):
+            continue
+        if email in seen_emails:
+            continue
+
+        display_raw = (realname or "").strip()
+        display: str | None
+        if display_raw:
+            collapsed = _WHITESPACE_RE.sub(" ", display_raw.lower())
+            display = normalize_participant(collapsed)
+        else:
+            display = None
+
+        seen_emails.add(email)
+        pairs.append((display, email))
+
+    return pairs