state-hub/api/models/workplan.py

import uuid
from datetime import date, datetime

from sqlalchemy import Date, DateTime, ForeignKey, Integer, String, Text
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship

from api.models.base import Base, TimestampMixin, new_uuid


class Workplan(Base, TimestampMixin):
    __tablename__ = "workplans"

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=new_uuid
    )
    topic_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True), ForeignKey("topics.id", ondelete="RESTRICT"), nullable=True, index=True
    )
    slug: Mapped[str] = mapped_column(String(100), unique=True, nullable=False, index=True)
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    status: Mapped[str] = mapped_column(
        String(20), nullable=False, default="active", server_default="active"
    )
    owner: Mapped[str | None] = mapped_column(String(100), nullable=True)
    due_date: Mapped[date | None] = mapped_column(Date, nullable=True)
    planning_priority: Mapped[str | None] = mapped_column(String(20), nullable=True, index=True)
    planning_order: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    execution_state: Mapped[str] = mapped_column(
        String(20), nullable=False, default="manual", server_default="manual", index=True
    )
    launch_mode: Mapped[str] = mapped_column(
        String(20), nullable=False, default="manual", server_default="manual", index=True
    )
    concurrency_mode: Mapped[str] = mapped_column(
        String(20), nullable=False, default="sequential", server_default="sequential", index=True
    )
    queue_rank: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    execution_group: Mapped[str | None] = mapped_column(String(100), nullable=True, index=True)
    scheduled_for: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True, index=True)

    repo_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("managed_repos.id", ondelete="RESTRICT"),
        nullable=False,
        index=True,
    )
    repo_goal_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("repo_goals.id", ondelete="SET NULL"),
        nullable=True,
        index=True,
    )
    backing_filename: Mapped[str | None] = mapped_column(String(255), nullable=True)
    # Projection provenance and retirement (ADR-012 decisions 2 and 7).
    # A retired record is one the forge no longer derives. It is not deleted:
    # hub-native records reference it with RESTRICT and must survive. It is not
    # `archived` either — that says the owner closed the work, which is a
    # different fact.
    projection_retired_at: Mapped["datetime | None"] = mapped_column(  # noqa: F821
        DateTime(timezone=True), nullable=True, index=True
    )
    projection_retired_reason: Mapped[str | None] = mapped_column(String(255), nullable=True)
    derived_from_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
    backing_relative_path: Mapped[str | None] = mapped_column(Text, nullable=True)
    backing_archived: Mapped[bool | None] = mapped_column(nullable=True)
    backing_synced_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True
    )

    topic: Mapped["Topic | None"] = relationship("Topic", back_populates="workplans")  # noqa: F821
    repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
    repo_goal: Mapped["RepoGoal"] = relationship("RepoGoal", back_populates="workplans", lazy="selectin")  # noqa: F821
    tasks: Mapped[list["Task"]] = relationship(  # noqa: F821
        "Task", back_populates="workplan", lazy="selectin"
    )
    decisions: Mapped[list["Decision"]] = relationship(  # noqa: F821
        "Decision", back_populates="workplan", lazy="selectin"
    )
    progress_events: Mapped[list["ProgressEvent"]] = relationship(  # noqa: F821
        "ProgressEvent", back_populates="workplan", lazy="selectin"
    )
    launch_requests: Mapped[list["WorkplanLaunchRequest"]] = relationship(  # noqa: F821
        "WorkplanLaunchRequest", back_populates="workplan", lazy="selectin"
    )