"""ImageProvenance — links an ImageRecord to a Post.

One image can have many provenance rows — different posts each contribute
metadata (enrich-on-duplicate rule, spec §3: a downloaded image that is a
pHash dupe of an existing record gets a NEW provenance row for the new post
appended, rather than the metadata being dropped). But the (image, post)
pair is unique — alembic 0021 enforces uq_image_provenance_image_post
after operator-flagged 2026-05-26 saw _apply_sidecar's existence-check +
INSERT race plant duplicates that then broke .scalar_one_or_none() on
every later deep-scan rederive (MultipleResultsFound).
"""

from datetime import datetime

from sqlalchemy import JSON, DateTime, ForeignKey, Integer, UniqueConstraint, func
from sqlalchemy.orm import Mapped, mapped_column

from .base import Base


class ImageProvenance(Base):
    __tablename__ = "image_provenance"
    __table_args__ = (
        UniqueConstraint(
            "image_record_id", "post_id",
            name="uq_image_provenance_image_post",
        ),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    image_record_id: Mapped[int] = mapped_column(
        ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False, index=True
    )
    post_id: Mapped[int] = mapped_column(
        ForeignKey("post.id", ondelete="CASCADE"), nullable=False, index=True
    )
    # Nullable since alembic 0030 — provenance rows for filesystem-imported
    # content with no subscription have NULL source_id. FK ondelete SET
    # NULL so deleting a Source detaches its provenance rows instead of
    # destroying the linkage between image and post.
    source_id: Mapped[int | None] = mapped_column(
        ForeignKey("source.id", ondelete="SET NULL"), nullable=True, index=True
    )
    # The archive PostAttachment this image was extracted FROM, when it came
    # out of a .zip/.rar rather than as a loose file (milestone #87). Lets the
    # provenance UI show the exact archive a file lives inside instead of every
    # attachment on the post. NULL for loose downloads and pre-backfill rows.
    # SET NULL so deleting the archive attachment never destroys the (image,
    # post) edge — it just forgets which archive it came from.
    from_attachment_id: Mapped[int | None] = mapped_column(
        ForeignKey("post_attachment.id", ondelete="SET NULL"),
        nullable=True, index=True,
    )
    captured_metadata: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    captured_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, server_default=func.now()
    )