Add engagement margin reporting

src/fin_hub/models/__init__.py

@@ -2,6 +2,7 @@
 
 from fin_hub.models.budget import Budget, BurnRate, Commitment, RunwayProjection, TokenSpend
 from fin_hub.models.service_cost import ServiceCost
+from fin_hub.models.engagement_price import EngagementPrice
 
 __all__ = [
     "Budget",
@@ -9,5 +10,6 @@ __all__ = [
     "Commitment",
     "RunwayProjection",
     "ServiceCost",
+    "EngagementPrice",
     "TokenSpend",
-]
+]

src/fin_hub/models/engagement_price.py

@@ -0,0 +1,33 @@
+"""Period-effective engagement pricing for client margin reporting."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import date
+
+from sqlalchemy import Date, Float, ForeignKey, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hub_core.models.base import Base, TimestampMixin
+
+
+class EngagementPrice(Base, TimestampMixin):
+    """A reporting entitlement price, not an invoice or payment record."""
+
+    __tablename__ = "fin_engagement_prices"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    client_id: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
+    application_id: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
+    app_instance_id: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
+    cost_attribution_key: Mapped[str] = mapped_column(String(423), nullable=False, index=True)
+    effective_from: Mapped[date] = mapped_column(Date, nullable=False, index=True)
+    effective_to: Mapped[date | None] = mapped_column(Date, nullable=True)
+    amount: Mapped[float] = mapped_column(Float, nullable=False)
+    currency: Mapped[str] = mapped_column(String(3), nullable=False, default="EUR")
+    source: Mapped[str] = mapped_column(String(128), nullable=False)
+    revision_of: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("fin_engagement_prices.id"), nullable=True
+    )
+    notes: Mapped[str | None] = mapped_column(String(512), nullable=True)