feat(models): add screening run and scoring tables

Adds the four Phase 4 persistence tables from ARCHITECTURE.md 6.6 as ORM
models plus the Alembic revision that creates them:

screening_runs one execution of the scoring pipeline over a job
candidate_scores one candidate's aggregated result within a run
requirement_verdicts the judge's call on one requirement
evidence_spans verbatim quotes backing a verdict

Three schema decisions worth recording:

- candidate_id, profile_id and triggered_by are plain uuid columns, not
foreign keys. The candidates, candidate_profiles and users tables the
architecture describes are not built in this repo, so declaring the
constraints would make the revision unrunnable. Same treatment
requirements.skill_id already documents for the unbuilt ESCO taxonomy.
- rubric_version_id and requirement_id are RESTRICT, not CASCADE. A score
is the record of which criteria produced a ranking, so the criteria must
outlive it.
- evidence_spans.chunk_id is SET NULL. Re-indexing a resume replaces its
chunks, and a citation survives that because resume_version_id plus the
character offsets locate the quote independently of any chunk row.

The ORM class is EvidenceSpanRecord rather than EvidenceSpan because
app.services.search already exposes an EvidenceSpan dataclass for
in-flight search results.

RED (commit 3a87be3):
pytest tests/unit/test_screening_models.py
33 failed - AttributeError: module 'app.models' has no attribute 'ScreeningRun'
pytest tests/unit/
FAILED test_migration_coverage.py::test_every_orm_table_is_created_by_some_migration
AssertionError: tables declared in app.models with no migration creating
them: ['candidate_scores', 'evidence_spans', 'requirement_verdicts',
'screening_runs']

GREEN:
pytest tests/unit/ all passed
pytest tests/integration/test_migrations.py 8 passed (live postgres)
pytest 615 passed
ruff check . All checks passed!
coverage 90.92% (was 90.61%), models.py 100%

The integration run covers upgrade-head, autogenerate-diff-is-empty,
idempotency and downgrade-then-upgrade reversibility against a real
database, so the revision is verified runnable in both directions.

serving/app/migrations/versions/20260802_0940_add_screening_run_scoring_tables.py

@@ -0,0 +1,276 @@
+"""add screening_runs, candidate_scores, requirement_verdicts, evidence_spans
+
+Revision ID: c3d4e5f6a7b8
+Revises: b2c3d4e5f6a7
+Create Date: 2026-08-02 09:40:00.000000+00:00
+
+candidate_scores.candidate_id / .profile_id and screening_runs.triggered_by are
+plain uuid columns rather than foreign keys: the candidates, candidate_profiles
+and users tables described in ARCHITECTURE.md 6.3-6.4 are not built in this
+repo, and declaring the constraints would make this revision unrunnable.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "c3d4e5f6a7b8"
+down_revision: str | None = "b2c3d4e5f6a7"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Apply this revision."""
+    op.create_table(
+        "screening_runs",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("tenant_id", sa.UUID(), nullable=False),
+        sa.Column("job_id", sa.UUID(), nullable=False),
+        sa.Column("rubric_version_id", sa.UUID(), nullable=False),
+        sa.Column("status", sa.String(length=32), nullable=False),
+        sa.Column("mode", sa.String(length=32), nullable=False),
+        sa.Column("candidate_count", sa.Integer(), nullable=False),
+        sa.Column("funnel_stage_counts", postgresql.JSONB(), nullable=True),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("workflow_id", sa.String(length=128), nullable=True),
+        sa.Column("triggered_by", sa.UUID(), nullable=True),
+        sa.Column("cost_usd", sa.Numeric(precision=10, scale=4), nullable=False),
+        sa.Column("total_input_tokens", sa.BigInteger(), nullable=False),
+        sa.Column("total_output_tokens", sa.BigInteger(), nullable=False),
+        sa.Column("cache_read_tokens", sa.BigInteger(), nullable=False),
+        sa.Column("cache_write_tokens", sa.BigInteger(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(["job_id"], ["jobs.id"], ondelete="CASCADE"),
+        # RESTRICT: a run is the record of which criteria produced a ranking, so
+        # the rubric version it cites must not be deletable out from under it.
+        sa.ForeignKeyConstraint(
+            ["rubric_version_id"], ["rubric_versions.id"], ondelete="RESTRICT"
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_screening_runs_tenant_id", "screening_runs", ["tenant_id"], unique=False
+    )
+    op.create_index(
+        "ix_screening_runs_tenant_job",
+        "screening_runs",
+        ["tenant_id", "job_id"],
+        unique=False,
+    )
+
+    op.create_table(
+        "candidate_scores",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("tenant_id", sa.UUID(), nullable=False),
+        sa.Column("run_id", sa.UUID(), nullable=False),
+        sa.Column("candidate_id", sa.UUID(), nullable=False),
+        sa.Column("profile_id", sa.UUID(), nullable=True),
+        # Two decimals for the reported score, four for the pre-rounding
+        # weighted sum, so a score stays replayable.
+        sa.Column("overall_score", sa.Numeric(precision=5, scale=2), nullable=False),
+        sa.Column("raw_weighted", sa.Numeric(precision=5, scale=4), nullable=False),
+        sa.Column("cap_applied", sa.Integer(), nullable=True),
+        sa.Column("rank", sa.Integer(), nullable=True),
+        sa.Column("retrieval_score", sa.Float(), nullable=True),
+        sa.Column("rerank_score", sa.Float(), nullable=True),
+        sa.Column("recommendation", sa.String(length=32), nullable=True),
+        sa.Column("recommendation_confidence", sa.Float(), nullable=True),
+        sa.Column("summary", sa.Text(), nullable=True),
+        sa.Column("aggregation_formula_version", sa.String(length=32), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(["run_id"], ["screening_runs.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "run_id", "candidate_id", name="uq_candidate_scores_run_candidate"
+        ),
+    )
+    op.create_index(
+        "ix_candidate_scores_tenant_id", "candidate_scores", ["tenant_id"], unique=False
+    )
+    op.create_index(
+        "ix_candidate_scores_tenant_run",
+        "candidate_scores",
+        ["tenant_id", "run_id"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_candidate_scores_run_rank",
+        "candidate_scores",
+        ["run_id", "rank"],
+        unique=False,
+    )
+
+    op.create_table(
+        "requirement_verdicts",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("tenant_id", sa.UUID(), nullable=False),
+        sa.Column("score_id", sa.UUID(), nullable=False),
+        sa.Column("requirement_id", sa.UUID(), nullable=False),
+        sa.Column("verdict", sa.String(length=16), nullable=False),
+        sa.Column("confidence", sa.Float(), nullable=False),
+        # Stored, not derived: the rubric can mint a new version with different
+        # weights, and a verdict must stay explainable against the weights that
+        # actually produced it.
+        sa.Column("weight_at_scoring", sa.Numeric(precision=5, scale=4), nullable=False),
+        sa.Column("contribution", sa.Numeric(precision=6, scale=4), nullable=False),
+        sa.Column("reasoning", sa.Text(), nullable=True),
+        sa.Column("judge_model", sa.String(length=128), nullable=True),
+        sa.Column("judge_prompt_version", sa.String(length=32), nullable=True),
+        sa.Column("judge_effort", sa.String(length=32), nullable=True),
+        sa.Column("cache_hit", sa.Boolean(), nullable=False),
+        sa.Column("input_tokens", sa.Integer(), nullable=False),
+        sa.Column("output_tokens", sa.Integer(), nullable=False),
+        sa.Column("latency_ms", sa.Integer(), nullable=False),
+        # The exposure record: exactly what the judge saw. Without it a
+        # "missing" verdict is indistinguishable from a retrieval failure.
+        sa.Column("retrieved_chunk_ids", postgresql.ARRAY(sa.UUID()), nullable=True),
+        sa.Column("result_cache_key", sa.String(length=64), nullable=True),
+        sa.Column("overridden_by", sa.UUID(), nullable=True),
+        sa.Column("override_verdict", sa.String(length=16), nullable=True),
+        sa.Column("override_reason", sa.Text(), nullable=True),
+        sa.Column("overridden_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["score_id"], ["candidate_scores.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(
+            ["requirement_id"], ["requirements.id"], ondelete="RESTRICT"
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "score_id", "requirement_id", name="uq_requirement_verdicts_score_req"
+        ),
+    )
+    op.create_index(
+        "ix_requirement_verdicts_tenant_id",
+        "requirement_verdicts",
+        ["tenant_id"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_requirement_verdicts_tenant_score",
+        "requirement_verdicts",
+        ["tenant_id", "score_id"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_requirement_verdicts_cache_key",
+        "requirement_verdicts",
+        ["result_cache_key"],
+        unique=False,
+    )
+
+    op.create_table(
+        "evidence_spans",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("tenant_id", sa.UUID(), nullable=False),
+        sa.Column("verdict_id", sa.UUID(), nullable=True),
+        sa.Column("resume_version_id", sa.UUID(), nullable=False),
+        sa.Column("chunk_id", sa.UUID(), nullable=True),
+        sa.Column("page", sa.Integer(), nullable=True),
+        sa.Column("start_char", sa.Integer(), nullable=False),
+        sa.Column("end_char", sa.Integer(), nullable=False),
+        sa.Column("quoted_text", sa.Text(), nullable=False),
+        # Set by the automated check that re-slices the resume at
+        # [start_char, end_char) and compares: the anti-hallucination gate.
+        sa.Column("verbatim_verified", sa.Boolean(), nullable=False),
+        sa.Column("relevance", sa.Float(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["verdict_id"], ["requirement_verdicts.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(
+            ["resume_version_id"], ["resume_versions.id"], ondelete="RESTRICT"
+        ),
+        # SET NULL: re-indexing a resume replaces its chunks, and the citation
+        # survives that because resume_version_id plus the character offsets
+        # locate the quote independently of any chunk row.
+        sa.ForeignKeyConstraint(["chunk_id"], ["resume_chunks.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_evidence_spans_tenant_id", "evidence_spans", ["tenant_id"], unique=False
+    )
+    op.create_index(
+        "ix_evidence_spans_tenant_verdict",
+        "evidence_spans",
+        ["tenant_id", "verdict_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    """Revert this revision."""
+    op.drop_index("ix_evidence_spans_tenant_verdict", table_name="evidence_spans")
+    op.drop_index("ix_evidence_spans_tenant_id", table_name="evidence_spans")
+    op.drop_table("evidence_spans")
+
+    op.drop_index(
+        "ix_requirement_verdicts_cache_key", table_name="requirement_verdicts"
+    )
+    op.drop_index(
+        "ix_requirement_verdicts_tenant_score", table_name="requirement_verdicts"
+    )
+    op.drop_index(
+        "ix_requirement_verdicts_tenant_id", table_name="requirement_verdicts"
+    )
+    op.drop_table("requirement_verdicts")
+
+    op.drop_index("ix_candidate_scores_run_rank", table_name="candidate_scores")
+    op.drop_index("ix_candidate_scores_tenant_run", table_name="candidate_scores")
+    op.drop_index("ix_candidate_scores_tenant_id", table_name="candidate_scores")
+    op.drop_table("candidate_scores")
+
+    op.drop_index("ix_screening_runs_tenant_job", table_name="screening_runs")
+    op.drop_index("ix_screening_runs_tenant_id", table_name="screening_runs")
+    op.drop_table("screening_runs")

serving/app/models.py

@@ -13,6 +13,7 @@
 
 from pgvector.sqlalchemy import HALFVEC, Vector
 from sqlalchemy import (
+    BigInteger,
     Boolean,
     DateTime,
     Float,
@@ -25,7 +26,7 @@
     UniqueConstraint,
     func,
 )
-from sqlalchemy.dialects.postgresql import JSONB, TSVECTOR
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB, TSVECTOR
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -343,3 +344,282 @@ class Requirement(TimestampMixin, Base):
     embedding: Mapped[list[float] | None] = mapped_column(HALFVEC(1024), nullable=True)
 
     rubric_version: Mapped[RubricVersion] = relationship(back_populates="requirements")
+
+
+class ScreeningRun(TimestampMixin, Base):
+    """One execution of the scoring pipeline over a job's candidate pool.
+
+    ``rubric_version_id`` is RESTRICT rather than CASCADE: a run is the record
+    of which criteria produced a ranking, so the rubric it cites must not be
+    deletable out from under it. The job itself CASCADEs — deleting a job is a
+    deliberate purge of everything scoped to it.
+
+    ``triggered_by`` is a plain uuid, not a foreign key: the ``users`` table
+    described in ARCHITECTURE.md §6.4 does not exist in this repo yet, and
+    declaring the constraint would make the migration unrunnable.
+    """
+
+    __tablename__ = "screening_runs"
+    __table_args__ = (Index("ix_screening_runs_tenant_job", "tenant_id", "job_id"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=False, index=True
+    )
+    job_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("jobs.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    rubric_version_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("rubric_versions.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="queued")
+    mode: Mapped[str] = mapped_column(String(32), nullable=False, default="interactive")
+    candidate_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    # Per-stage survivor counts for the retrieval funnel, so a shortlist can be
+    # explained as "N of M candidates reached the judge" without re-running it.
+    funnel_stage_counts: Mapped[dict[str, object] | None] = mapped_column(
+        JSONB, nullable=True
+    )
+
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    completed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    workflow_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
+    triggered_by: Mapped[uuid.UUID | None] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=True
+    )
+
+    cost_usd: Mapped[Decimal] = mapped_column(
+        Numeric(10, 4), nullable=False, default=Decimal("0")
+    )
+    total_input_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    total_output_tokens: Mapped[int] = mapped_column(
+        BigInteger, nullable=False, default=0
+    )
+    cache_read_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    cache_write_tokens: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+
+    scores: Mapped[list[CandidateScore]] = relationship(
+        back_populates="run",
+        cascade="all, delete-orphan",
+        lazy="noload",
+    )
+
+
+class CandidateScore(TimestampMixin, Base):
+    """One candidate's aggregated result within a run.
+
+    ``raw_weighted`` keeps four decimal places while ``overall_score`` keeps
+    two: the weighted sum is the input to capping and rounding, and storing it
+    pre-rounding is what makes a score replayable. ``cap_applied`` is NULL when
+    no must-have cap fired, so "was this candidate capped" is answerable without
+    recomputing the rubric.
+
+    ``candidate_id`` and ``profile_id`` are plain uuids rather than foreign
+    keys: the ``candidates`` and ``candidate_profiles`` tables described in
+    ARCHITECTURE.md §6.3 are not built in this repo, and declaring the
+    constraints would make the migration unrunnable.
+    """
+
+    __tablename__ = "candidate_scores"
+    __table_args__ = (
+        UniqueConstraint(
+            "run_id", "candidate_id", name="uq_candidate_scores_run_candidate"
+        ),
+        Index("ix_candidate_scores_run_rank", "run_id", "rank"),
+        Index("ix_candidate_scores_tenant_run", "tenant_id", "run_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=False, index=True
+    )
+    run_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("screening_runs.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    candidate_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=False
+    )
+    profile_id: Mapped[uuid.UUID | None] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=True
+    )
+
+    overall_score: Mapped[Decimal] = mapped_column(Numeric(5, 2), nullable=False)
+    raw_weighted: Mapped[Decimal] = mapped_column(Numeric(5, 4), nullable=False)
+    cap_applied: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # Assigned in a second pass once every candidate in the run is scored, so a
+    # partially-completed run has scores without ranks rather than wrong ranks.
+    rank: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    retrieval_score: Mapped[float | None] = mapped_column(Float, nullable=True)
+    rerank_score: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    recommendation: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    recommendation_confidence: Mapped[float | None] = mapped_column(Float, nullable=True)
+    summary: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # Provenance for replay: which aggregation formula produced this number.
+    aggregation_formula_version: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="v1"
+    )
+
+    run: Mapped[ScreeningRun] = relationship(back_populates="scores")
+    verdicts: Mapped[list[RequirementVerdict]] = relationship(
+        back_populates="score",
+        cascade="all, delete-orphan",
+        lazy="noload",
+    )
+
+
+class RequirementVerdict(TimestampMixin, Base):
+    """The judge's call on one requirement for one candidate.
+
+    ``weight_at_scoring`` and ``contribution`` are stored rather than derived:
+    the rubric can mint a new version with different weights, and a verdict must
+    stay explainable against the weights that actually produced it.
+
+    ``retrieved_chunk_ids`` is the exposure record — exactly what the judge saw.
+    Without it a "missing" verdict is indistinguishable from a retrieval failure.
+
+    ``requirement_id`` is RESTRICT: a verdict cites a criterion, so the
+    criterion must outlive it. Override columns are all nullable and set
+    together when a human corrects the judge.
+    """
+
+    __tablename__ = "requirement_verdicts"
+    __table_args__ = (
+        UniqueConstraint(
+            "score_id", "requirement_id", name="uq_requirement_verdicts_score_req"
+        ),
+        Index("ix_requirement_verdicts_tenant_score", "tenant_id", "score_id"),
+        Index("ix_requirement_verdicts_cache_key", "result_cache_key"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=False, index=True
+    )
+    score_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("candidate_scores.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    requirement_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("requirements.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    verdict: Mapped[str] = mapped_column(String(16), nullable=False)
+    confidence: Mapped[float] = mapped_column(Float, nullable=False)
+    weight_at_scoring: Mapped[Decimal] = mapped_column(Numeric(5, 4), nullable=False)
+    contribution: Mapped[Decimal] = mapped_column(Numeric(6, 4), nullable=False)
+    reasoning: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    judge_model: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    judge_prompt_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    judge_effort: Mapped[str | None] = mapped_column(String(32), nullable=True)
+
+    cache_hit: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    input_tokens: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    output_tokens: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    latency_ms: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    retrieved_chunk_ids: Mapped[list[uuid.UUID] | None] = mapped_column(
+        ARRAY(PG_UUID(as_uuid=True)), nullable=True
+    )
+    result_cache_key: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    overridden_by: Mapped[uuid.UUID | None] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=True
+    )
+    override_verdict: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    override_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    overridden_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    score: Mapped[CandidateScore] = relationship(back_populates="verdicts")
+    evidence_spans: Mapped[list[EvidenceSpanRecord]] = relationship(
+        back_populates="verdict",
+        cascade="all, delete-orphan",
+        lazy="noload",
+    )
+
+
+class EvidenceSpanRecord(TimestampMixin, Base):
+    """A verbatim quote from a resume backing one verdict.
+
+    Named ``EvidenceSpanRecord`` rather than ``EvidenceSpan`` because
+    ``app.services.search`` already exposes an ``EvidenceSpan`` dataclass for
+    in-flight search results; this is the persisted form.
+
+    ``verbatim_verified`` is set by the automated check that re-slices the
+    resume text at ``[start_char, end_char)`` and compares it to
+    ``quoted_text`` — the anti-hallucination gate. A row with it False is a
+    quote the judge produced that the source does not contain.
+
+    ``chunk_id`` is SET NULL on delete: re-indexing a resume replaces its
+    chunks, and the citation survives that because ``resume_version_id`` plus
+    the character offsets locate the quote independently of any chunk row.
+    """
+
+    __tablename__ = "evidence_spans"
+    __table_args__ = (
+        Index("ix_evidence_spans_tenant_verdict", "tenant_id", "verdict_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    tenant_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True), nullable=False, index=True
+    )
+    # Nullable so a span can be recorded while its verdict is still being built.
+    verdict_id: Mapped[uuid.UUID | None] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("requirement_verdicts.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    resume_version_id: Mapped[uuid.UUID] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("resume_versions.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    chunk_id: Mapped[uuid.UUID | None] = mapped_column(
+        PG_UUID(as_uuid=True),
+        ForeignKey("resume_chunks.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+
+    page: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    start_char: Mapped[int] = mapped_column(Integer, nullable=False)
+    end_char: Mapped[int] = mapped_column(Integer, nullable=False)
+    quoted_text: Mapped[str] = mapped_column(Text, nullable=False)
+    verbatim_verified: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    relevance: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    verdict: Mapped[RequirementVerdict | None] = relationship(
+        back_populates="evidence_spans"
+    )

tests/integration/test_migrations.py

@@ -17,6 +17,10 @@
     "jobs",
     "rubric_versions",
     "requirements",
+    "screening_runs",
+    "candidate_scores",
+    "requirement_verdicts",
+    "evidence_spans",
 }