Add governed form handoffs

src/govoplan_forms_runtime/backend/db/models.py

@@ -4,7 +4,15 @@ from datetime import datetime
 from typing import Any
 import uuid
 
-from sqlalchemy import DateTime, ForeignKey, Index, Integer, JSON, String, UniqueConstraint
+from sqlalchemy import (
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    JSON,
+    String,
+    UniqueConstraint,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from govoplan_core.db.base import Base, TimestampMixin
@@ -125,8 +133,65 @@ class FormInstanceEvent(Base, TimestampMixin):
     payload: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
 
 
+class FormHandoffEffect(Base, TimestampMixin):
+    __tablename__ = "form_handoff_effects"
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id",
+            "effect_id",
+            name="uq_form_handoff_effect",
+        ),
+        UniqueConstraint(
+            "tenant_id",
+            "idempotency_key",
+            name="uq_form_handoff_idempotency",
+        ),
+        UniqueConstraint(
+            "tenant_id",
+            "provider_key",
+            name="uq_form_handoff_provider_key",
+        ),
+        Index(
+            "ix_form_handoff_instance_state",
+            "tenant_id",
+            "instance_id",
+            "state",
+        ),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False, index=True)
+    instance_id: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+    effect_id: Mapped[str] = mapped_column(String(36), nullable=False, index=True)
+    instance_revision: Mapped[int] = mapped_column(Integer, nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    provider_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    request_sha256: Mapped[str] = mapped_column(String(64), nullable=False)
+    binding_kind: Mapped[str] = mapped_column(String(30), nullable=False, index=True)
+    binding_reference: Mapped[str] = mapped_column(String(500), nullable=False)
+    provider_capability: Mapped[str] = mapped_column(String(120), nullable=False)
+    state: Mapped[str] = mapped_column(String(30), nullable=False, index=True)
+    attempt_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    requested_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, index=True
+    )
+    resolved_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True, index=True
+    )
+    target_ref: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
+    href: Mapped[str | None] = mapped_column(String(2000), nullable=True)
+    evidence: Mapped[list[dict[str, Any]]] = mapped_column(
+        JSON, default=list, nullable=False
+    )
+    last_error: Mapped[str | None] = mapped_column(String(2000), nullable=True)
+    details: Mapped[dict[str, Any]] = mapped_column(
+        "metadata", JSON, default=dict, nullable=False
+    )
+
+
 __all__ = [
     "FormInstanceEvent",
+    "FormHandoffEffect",
     "FormInstanceIdentity",
     "FormInstanceRevision",
 ]