leads-cli 0.1.0__py3-none-any.whl

company_discovery/db/enrichment_repository.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import uuid4
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import joinedload
+
+from company_discovery.db.models import (
+    CandidateEvaluationRow,
+    CompanyCandidateRow,
+    DiscoveryRunRow,
+    EnrichmentFactRow,
+    EnrichmentItemRow,
+    EnrichmentRunRow,
+)
+from company_discovery.db.repository import CandidateNotFoundError, RunNotFoundError
+from company_discovery.db.session import Database
+from company_discovery.domain.models import EnrichmentItem, EnrichmentProfile, EnrichmentSummary
+
+
+class EnrichmentRunNotFoundError(LookupError):
+    pass
+
+
+class EnrichmentRepository:
+    RUN_ID_PREFIX = "company-enrich-"
+    CREATE_RUN_ATTEMPTS = 5
+
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    def discovery_candidates(self, run_id: str, bucket: str, limit: int | None) -> list[dict[str, Any]]:
+        with self.database.session() as session:
+            run = session.get(DiscoveryRunRow, run_id)
+            if run is None:
+                raise RunNotFoundError(f"run not found: {run_id}")
+            if run.status != "completed":
+                raise ValueError(f"discovery run {run_id} is {run.status}, not completed")
+            statement = (
+                select(CandidateEvaluationRow, CompanyCandidateRow)
+                .join(CompanyCandidateRow)
+                .where(
+                    CandidateEvaluationRow.run_id == run_id,
+                    CandidateEvaluationRow.bucket == bucket,
+                )
+                .order_by(CandidateEvaluationRow.id)
+            )
+            if limit is not None:
+                statement = statement.limit(limit)
+            rows = session.execute(statement).all()
+            return [
+                {
+                    "candidate_id": candidate.id,
+                    "company": candidate.normalized_payload,
+                    "evaluation": evaluation.evaluation_payload,
+                    "bucket": evaluation.bucket,
+                    "source": evaluation.source,
+                    "spec": run.spec_payload,
+                }
+                for evaluation, candidate in rows
+            ]
+
+    def create_run(self, discovery_run_id: str, bucket: str, options: dict[str, Any]) -> str:
+        for _ in range(self.CREATE_RUN_ATTEMPTS):
+            try:
+                with self.database.session() as session:
+                    if session.get(DiscoveryRunRow, discovery_run_id) is None:
+                        raise RunNotFoundError(f"run not found: {discovery_run_id}")
+                    run_id = self._new_run_id()
+                    session.add(
+                        EnrichmentRunRow(
+                            id=run_id,
+                            discovery_run_id=discovery_run_id,
+                            bucket=bucket,
+                            options_payload=options,
+                        )
+                    )
+                return run_id
+            except IntegrityError:
+                continue
+        raise RuntimeError("unable to allocate a unique enrichment run id")
+
+    def fresh_profile(self, candidate_id: int, freshness_days: int) -> EnrichmentProfile:
+        cutoff = datetime.now(UTC) - timedelta(days=freshness_days)
+        latest = (
+            select(
+                EnrichmentFactRow.fact_kind,
+                func.max(EnrichmentFactRow.id).label("latest_id"),
+            )
+            .where(
+                EnrichmentFactRow.candidate_id == candidate_id,
+                EnrichmentFactRow.observed_at >= cutoff,
+            )
+            .group_by(EnrichmentFactRow.fact_kind)
+            .subquery()
+        )
+        with self.database.session() as session:
+            facts = session.scalars(
+                select(EnrichmentFactRow).join(latest, EnrichmentFactRow.id == latest.c.latest_id)
+            ).all()
+        payload = {fact.fact_kind: fact.fact_payload for fact in facts}
+        return EnrichmentProfile.model_validate(payload)
+
+    def save_item(self, run_id: str, item: EnrichmentItem) -> None:
+        with self.database.session() as session:
+            if session.get(CompanyCandidateRow, item.company_id) is None:
+                raise CandidateNotFoundError(f"candidate not found: {item.company_id}")
+            session.add(
+                EnrichmentItemRow(
+                    run_id=run_id,
+                    candidate_id=item.company_id,
+                    discovery_snapshot=item.discovery,
+                    enrichment_payload=item.enrichment.model_dump(mode="json"),
+                    inherited_status={key: value.value for key, value in item.inherited_status.items()},
+                    outcome=item.outcome.value,
+                    conflicts=item.conflicts,
+                    review_flags=item.review_flags,
+                    trace_payload=item.trace,
+                )
+            )
+            for kind in ("phone", "location", "independence", "linkedin"):
+                fact = getattr(item.enrichment, kind)
+                if fact is not None:
+                    session.add(
+                        EnrichmentFactRow(
+                            candidate_id=item.company_id,
+                            enrichment_run_id=run_id,
+                            fact_kind=kind,
+                            fact_payload=fact.model_dump(mode="json"),
+                            observed_at=fact.observed_at,
+                        )
+                    )
+
+    def complete_run(self, run_id: str, summary: EnrichmentSummary, paths: dict[str, str]) -> None:
+        with self.database.session() as session:
+            row = self._require_run(session, run_id)
+            row.status = "completed"
+            row.summary_payload = summary.model_dump(mode="json")
+            row.artifact_paths = paths
+            row.completed_at = datetime.now(UTC)
+
+    def fail_run(self, run_id: str, error: Exception) -> None:
+        with self.database.session() as session:
+            row = self._require_run(session, run_id)
+            row.status = "failed"
+            row.error_message = str(error)
+            row.completed_at = datetime.now(UTC)
+
+    def set_artifacts(self, run_id: str, paths: dict[str, str]) -> None:
+        with self.database.session() as session:
+            self._require_run(session, run_id).artifact_paths = paths
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        with self.database.session() as session:
+            row = session.scalar(
+                select(EnrichmentRunRow)
+                .options(joinedload(EnrichmentRunRow.items))
+                .where(EnrichmentRunRow.id == run_id)
+            )
+            if row is None:
+                raise EnrichmentRunNotFoundError(f"enrichment run not found: {run_id}")
+            return {
+                "run_id": row.id,
+                "discovery_run_id": row.discovery_run_id,
+                "bucket": row.bucket,
+                "options": row.options_payload,
+                "status": row.status,
+                "summary": row.summary_payload,
+                "artifacts": row.artifact_paths,
+                "error": row.error_message,
+                "created_at": row.created_at.isoformat(),
+                "completed_at": row.completed_at.isoformat() if row.completed_at else None,
+                "items": [
+                    {
+                        "company_id": item.candidate_id,
+                        "discovery": item.discovery_snapshot,
+                        "enrichment": item.enrichment_payload,
+                        "inherited_status": item.inherited_status,
+                        "outcome": item.outcome,
+                        "conflicts": item.conflicts,
+                        "review_flags": item.review_flags,
+                        "trace": item.trace_payload,
+                    }
+                    for item in row.items
+                ],
+            }
+
+    def inspect_item(self, run_id: str, domain: str) -> dict[str, Any]:
+        payload = self.get_run(run_id)
+        for item in payload["items"]:
+            if item["discovery"]["domain"] == domain:
+                return item
+        raise CandidateNotFoundError(f"domain {domain} was not enriched in run {run_id}")
+
+    @staticmethod
+    def _require_run(session: Any, run_id: str) -> EnrichmentRunRow:
+        row = session.get(EnrichmentRunRow, run_id)
+        if row is None:
+            raise EnrichmentRunNotFoundError(f"enrichment run not found: {run_id}")
+        return row
+
+    @classmethod
+    def _new_run_id(cls) -> str:
+        return f"{cls.RUN_ID_PREFIX}{uuid4().hex[:12]}"

company_discovery/db/models.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Index, Integer, JSON, String, Text, UniqueConstraint
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class DiscoveryRunRow(Base):
+    __tablename__ = "company_discovery_runs"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True)
+    spec_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    source_spec_path: Mapped[str | None] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="running")
+    summary_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    artifact_paths: Mapped[dict[str, str]] = mapped_column(JSON, nullable=False, default=dict)
+    error_message: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    queries: Mapped[list[DiscoveryQueryRow]] = relationship(
+        back_populates="run", cascade="all, delete-orphan", order_by="DiscoveryQueryRow.query_order"
+    )
+    evaluations: Mapped[list[CandidateEvaluationRow]] = relationship(
+        back_populates="run", cascade="all, delete-orphan"
+    )
+
+
+class DiscoveryQueryRow(Base):
+    __tablename__ = "company_discovery_queries"
+    __table_args__ = (UniqueConstraint("run_id", "query_order"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(ForeignKey("company_discovery_runs.id", ondelete="CASCADE"), index=True)
+    query_text: Mapped[str] = mapped_column(Text, nullable=False)
+    query_order: Mapped[int] = mapped_column(Integer, nullable=False)
+    rationale: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    result_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    cost_dollars: Mapped[float] = mapped_column(Float, default=0, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[DiscoveryRunRow] = relationship(back_populates="queries")
+    raw_results: Mapped[list[RawResultRow]] = relationship(
+        back_populates="query", cascade="all, delete-orphan"
+    )
+
+
+class RawResultRow(Base):
+    __tablename__ = "company_discovery_raw_results"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(ForeignKey("company_discovery_runs.id", ondelete="CASCADE"), index=True)
+    query_id: Mapped[int] = mapped_column(ForeignKey("company_discovery_queries.id", ondelete="CASCADE"), index=True)
+    result_position: Mapped[int] = mapped_column(Integer, nullable=False)
+    observed_url: Mapped[str] = mapped_column(Text, nullable=False)
+    observed_title: Mapped[str] = mapped_column(Text, nullable=False)
+    raw_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    query: Mapped[DiscoveryQueryRow] = relationship(back_populates="raw_results")
+
+
+class CompanyCandidateRow(Base):
+    __tablename__ = "company_candidates"
+    __table_args__ = (
+        Index("ix_company_candidates_market", "vertical", "country", "state"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    canonical_name: Mapped[str] = mapped_column(Text, nullable=False)
+    domain: Mapped[str] = mapped_column(String(255), nullable=False, unique=True, index=True)
+    dedupe_key: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    normalized_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    vertical: Mapped[str | None] = mapped_column(String(128), index=True)
+    country: Mapped[str | None] = mapped_column(String(2), index=True)
+    state: Mapped[str | None] = mapped_column(String(8), index=True)
+    employee_min: Mapped[int | None] = mapped_column(Integer)
+    employee_max: Mapped[int | None] = mapped_column(Integer)
+    ownership_type: Mapped[str | None] = mapped_column(String(128), index=True)
+    prior_bucket: Mapped[str | None] = mapped_column(String(32), index=True)
+    prior_reason: Mapped[str | None] = mapped_column(Text)
+    excluded: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    first_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    last_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    last_evaluated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    evaluations: Mapped[list[CandidateEvaluationRow]] = relationship(back_populates="candidate")
+
+
+class CandidateEvaluationRow(Base):
+    __tablename__ = "company_candidate_evaluations"
+    __table_args__ = (UniqueConstraint("run_id", "candidate_id"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(ForeignKey("company_discovery_runs.id", ondelete="CASCADE"), index=True)
+    candidate_id: Mapped[int] = mapped_column(ForeignKey("company_candidates.id"), index=True)
+    evaluation_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    fit_outcome: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+    bucket: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+    reason: Mapped[str] = mapped_column(Text, nullable=False)
+    reason_codes: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    source: Mapped[str] = mapped_column(String(32), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[DiscoveryRunRow] = relationship(back_populates="evaluations")
+    candidate: Mapped[CompanyCandidateRow] = relationship(back_populates="evaluations")
+
+
+class EnrichmentRunRow(Base):
+    __tablename__ = "company_enrichment_runs"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True)
+    discovery_run_id: Mapped[str] = mapped_column(
+        ForeignKey("company_discovery_runs.id"), nullable=False, index=True
+    )
+    bucket: Mapped[str] = mapped_column(String(32), nullable=False, default="selected")
+    options_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="running")
+    summary_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    artifact_paths: Mapped[dict[str, str]] = mapped_column(JSON, nullable=False, default=dict)
+    error_message: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    items: Mapped[list[EnrichmentItemRow]] = relationship(
+        back_populates="run", cascade="all, delete-orphan", order_by="EnrichmentItemRow.id"
+    )
+
+
+class EnrichmentItemRow(Base):
+    __tablename__ = "company_enrichment_items"
+    __table_args__ = (UniqueConstraint("run_id", "candidate_id"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("company_enrichment_runs.id", ondelete="CASCADE"), index=True
+    )
+    candidate_id: Mapped[int] = mapped_column(ForeignKey("company_candidates.id"), index=True)
+    discovery_snapshot: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    enrichment_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    inherited_status: Mapped[dict[str, str]] = mapped_column(JSON, nullable=False)
+    outcome: Mapped[str] = mapped_column(String(48), nullable=False, index=True)
+    conflicts: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    review_flags: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    trace_payload: Mapped[list[dict[str, Any]]] = mapped_column(JSON, nullable=False, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[EnrichmentRunRow] = relationship(back_populates="items")
+
+
+class EnrichmentFactRow(Base):
+    __tablename__ = "company_enrichment_facts"
+    __table_args__ = (Index("ix_enrichment_fact_latest", "candidate_id", "fact_kind", "observed_at"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    candidate_id: Mapped[int] = mapped_column(ForeignKey("company_candidates.id"), index=True)
+    enrichment_run_id: Mapped[str] = mapped_column(ForeignKey("company_enrichment_runs.id"), index=True)
+    fact_kind: Mapped[str] = mapped_column(String(32), nullable=False)
+    fact_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    observed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+
+class ContactDiscoveryRunRow(Base):
+    __tablename__ = "contact_discovery_runs"
+
+    id: Mapped[str] = mapped_column(String(40), primary_key=True)
+    enrichment_run_id: Mapped[str] = mapped_column(
+        ForeignKey("company_enrichment_runs.id"), nullable=False, index=True
+    )
+    spec_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    source_spec_path: Mapped[str | None] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="running")
+    summary_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    artifact_paths: Mapped[dict[str, str]] = mapped_column(JSON, nullable=False, default=dict)
+    error_message: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    queries: Mapped[list[ContactDiscoveryQueryRow]] = relationship(
+        back_populates="run",
+        cascade="all, delete-orphan",
+        order_by="ContactDiscoveryQueryRow.id",
+    )
+    evaluations: Mapped[list[ContactEvaluationRow]] = relationship(
+        back_populates="run", cascade="all, delete-orphan"
+    )
+
+
+class ContactDiscoveryQueryRow(Base):
+    __tablename__ = "contact_discovery_queries"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("contact_discovery_runs.id", ondelete="CASCADE"), index=True
+    )
+    company_domain: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    role_key: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    query_text: Mapped[str] = mapped_column(Text, nullable=False)
+    result_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    cost_dollars: Mapped[float] = mapped_column(Float, nullable=False, default=0)
+    raw_results: Mapped[list[dict[str, Any]]] = mapped_column(JSON, nullable=False, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[ContactDiscoveryRunRow] = relationship(back_populates="queries")
+
+
+class ContactCandidateRow(Base):
+    __tablename__ = "contact_candidates"
+    __table_args__ = (
+        UniqueConstraint("company_domain", "identity_key"),
+        Index("ix_contact_candidates_company", "company_domain", "normalized_name"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    company_candidate_id: Mapped[int] = mapped_column(
+        ForeignKey("company_candidates.id"), nullable=False, index=True
+    )
+    company_name: Mapped[str] = mapped_column(Text, nullable=False)
+    company_domain: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    full_name: Mapped[str] = mapped_column(Text, nullable=False)
+    normalized_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    identity_key: Mapped[str] = mapped_column(String(512), nullable=False)
+    title: Mapped[str] = mapped_column(Text, nullable=False)
+    linkedin_url: Mapped[str | None] = mapped_column(Text)
+    source_urls: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    evidence: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    first_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    last_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    evaluations: Mapped[list[ContactEvaluationRow]] = relationship(back_populates="candidate")
+
+
+class ContactEvaluationRow(Base):
+    __tablename__ = "contact_evaluations"
+    __table_args__ = (UniqueConstraint("run_id", "candidate_id", "role_key"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("contact_discovery_runs.id", ondelete="CASCADE"), index=True
+    )
+    candidate_id: Mapped[int] = mapped_column(
+        ForeignKey("contact_candidates.id"), nullable=False, index=True
+    )
+    role_key: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    verdict: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
+    reason: Mapped[str] = mapped_column(Text, nullable=False)
+    current_company_match: Mapped[str] = mapped_column(String(16), nullable=False)
+    role_match: Mapped[str] = mapped_column(String(16), nullable=False)
+    identity_clear: Mapped[bool] = mapped_column(Boolean, nullable=False)
+    source: Mapped[str] = mapped_column(String(32), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[ContactDiscoveryRunRow] = relationship(back_populates="evaluations")
+    candidate: Mapped[ContactCandidateRow] = relationship(back_populates="evaluations")
+
+
+class ContactEnrichmentRunRow(Base):
+    __tablename__ = "contact_enrichment_runs"
+
+    id: Mapped[str] = mapped_column(String(48), primary_key=True)
+    contact_discovery_run_id: Mapped[str] = mapped_column(
+        ForeignKey("contact_discovery_runs.id"), nullable=False, index=True
+    )
+    options_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="running")
+    summary_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    artifact_paths: Mapped[dict[str, str]] = mapped_column(JSON, nullable=False, default=dict)
+    error_message: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    items: Mapped[list[ContactEnrichmentItemRow]] = relationship(
+        back_populates="run", cascade="all, delete-orphan", order_by="ContactEnrichmentItemRow.id"
+    )
+
+
+class ContactEnrichmentItemRow(Base):
+    __tablename__ = "contact_enrichment_items"
+    __table_args__ = (UniqueConstraint("run_id", "candidate_id"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("contact_enrichment_runs.id", ondelete="CASCADE"), index=True
+    )
+    candidate_id: Mapped[int] = mapped_column(
+        ForeignKey("contact_candidates.id"), nullable=False, index=True
+    )
+    discovery_snapshot: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    channels_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    outcome: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
+    review_flags: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    trace_payload: Mapped[list[dict[str, Any]]] = mapped_column(JSON, nullable=False, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)
+
+    run: Mapped[ContactEnrichmentRunRow] = relationship(back_populates="items")
+
+
+class ContactEnrichmentFactRow(Base):
+    __tablename__ = "contact_enrichment_facts"
+    __table_args__ = (
+        Index("ix_contact_enrichment_fact_latest", "candidate_id", "observed_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    candidate_id: Mapped[int] = mapped_column(
+        ForeignKey("contact_candidates.id"), nullable=False, index=True
+    )
+    enrichment_run_id: Mapped[str] = mapped_column(
+        ForeignKey("contact_enrichment_runs.id"), nullable=False, index=True
+    )
+    channels_payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False)
+    outcome: Mapped[str] = mapped_column(String(16), nullable=False)
+    review_flags: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    observed_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, nullable=False)