Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

31.7 KB
Raw Blame
import json
import uuid
import typing
import datetime as dt
import dataclasses
from datetime import datetime

from django.db.models import Q
from django.utils import timezone as tz

import temporalio.activity
from structlog import get_logger
from temporalio.exceptions import ApplicationError

from posthog.sync import database_sync_to_async
from posthog.utils import pluralize

from products.dashboards.backend.models.dashboard_tile import DashboardTile
from products.exports.backend.models.exported_asset import ExportedAsset
from products.product_analytics.backend.facade.models import Insight
from products.subscriptions.backend.logic import _capture_delivery_failed_event
from products.subscriptions.backend.logic.auto_disable import (
    UNSUPPORTED_TARGET_DISABLE_REASON,
    disable_invalid_subscription,
    get_assets_owner_disable_reason,
    get_subscription_disable_reason,
)
from products.subscriptions.backend.logic.email_subscriptions import send_email_subscription_report
from products.subscriptions.backend.logic.failure_notifications import (
    create_subscription_delivery_failure_notification,
    send_subscription_delivery_failure_email,
)
from products.subscriptions.backend.logic.slack_subscriptions import send_slack_message_with_integration_async
from products.subscriptions.backend.logic.subscription_utils import (
    ASSET_GENERATION_FAILED_MESSAGE,
    MAX_INSIGHTS,
    _has_asset_failed,
)
from products.subscriptions.backend.logic.teams_subscriptions import build_teams_subscription_card
from products.subscriptions.backend.models.subscription import Subscription, SubscriptionDelivery
from products.subscriptions.backend.models.subscription_context import SubscriptionContext
from products.subscriptions.backend.temporal.ai_subscription.activities import _deliver_ai_subscription
from products.subscriptions.backend.temporal.delivery_common import (
    auto_disable_and_return,
    deliver_email,
    deliver_slack,
)
from products.subscriptions.backend.temporal.delivery_webhook import deliver_teams_webhook
from products.subscriptions.backend.temporal.insight_snapshot import (
    build_initial_content_snapshot,
    build_insight_delivery_snapshot,
)
from products.subscriptions.backend.temporal.types import (
    CreateDeliveryRecordInputs,
    CreateExportAssetsInputs,
    CreateExportAssetsResult,
    DeliverSubscriptionInputs,
    DeliverSubscriptionResult,
    DeliveryAbort,
    DueSubscription,
    ExportAssetPreparationStatus,
    FetchDueSubscriptionsActivityInputs,
    NoExportableInsightsContext,
    NoExportableInsightsReason,
    RecipientResult,
    RecipientResultStatus,
    UpdateDeliveryRecordInputs,
)

LOGGER = get_logger(__name__)

# Used only as the recipient_results error message — `no_assets` doesn't auto-disable
# (it indicates a transient resolve failure that retries can recover from).
NO_ASSETS_REASON = "No assets to deliver — likely a transient export pipeline failure; will retry on next schedule"
# Plain-English twin of NO_ASSETS_REASON for the delivery-history UI: "assets" and "export pipeline"
# are internal jargon subscribers won't parse.
NO_ASSETS_HUMAN_READABLE_REASON = (
    "Nothing could be generated to send this time. We'll try again on the next scheduled run."
)


class NoExportableInsightsError(Exception):
    pass


@dataclasses.dataclass
class ResolvedExportableInsights:
    tile_insight_pairs: list[tuple[DashboardTile | None, Insight]]
    available_insight_count: int
    selected_insight_count: int
    no_exportable_reason: str | None


async def _resolve_exportable_insights(subscription: Subscription) -> ResolvedExportableInsights:
    dashboard = subscription.dashboard
    if dashboard:
        if dashboard.deleted:
            return ResolvedExportableInsights(
                tile_insight_pairs=[],
                available_insight_count=0,
                selected_insight_count=0,
                no_exportable_reason=NoExportableInsightsReason.DASHBOARD_DELETED,
            )

        tiles = await database_sync_to_async(
            lambda: list(
                dashboard.tiles.select_related("insight").filter(insight__isnull=False, insight__deleted=False).all()
            ),
            thread_sensitive=False,
        )()
        tiles.sort(
            key=lambda x: (
                (x.layouts or {}).get("sm", {}).get("y", 100),
                (x.layouts or {}).get("sm", {}).get("x", 100),
            )
        )
        tile_insight_pairs: list[tuple[DashboardTile | None, Insight]] = [
            (tile, tile.insight) for tile in tiles if tile.insight
        ]
        available_insight_count = len(tile_insight_pairs)
        selected_ids = await database_sync_to_async(
            lambda: (
                set(subscription.dashboard_export_insights.values_list("id", flat=True))
                if subscription.dashboard_export_insights.exists()
                else None
            ),
            thread_sensitive=False,
        )()
        if selected_ids:
            selected_pairs: list[tuple[DashboardTile | None, Insight]] = [
                (tile, insight) for tile, insight in tile_insight_pairs if insight.id in selected_ids
            ]
            return ResolvedExportableInsights(
                tile_insight_pairs=selected_pairs,
                available_insight_count=available_insight_count,
                selected_insight_count=len(selected_ids),
                no_exportable_reason=(
                    None if selected_pairs else NoExportableInsightsReason.SELECTED_INSIGHTS_NO_LONGER_AVAILABLE
                ),
            )

        return ResolvedExportableInsights(
            tile_insight_pairs=tile_insight_pairs,
            available_insight_count=available_insight_count,
            selected_insight_count=0,
            no_exportable_reason=None if tile_insight_pairs else NoExportableInsightsReason.EMPTY_DASHBOARD,
        )

    if subscription.insight and not subscription.insight.deleted:
        return ResolvedExportableInsights(
            tile_insight_pairs=[(None, subscription.insight)],
            available_insight_count=1,
            selected_insight_count=0,
            no_exportable_reason=None,
        )

    return ResolvedExportableInsights(
        tile_insight_pairs=[],
        available_insight_count=0,
        selected_insight_count=0,
        no_exportable_reason=NoExportableInsightsReason.MISSING_RESOURCE,
    )


async def _persist_content_snapshot(
    *,
    delivery_id: uuid.UUID,
    total_insight_count: int,
    insight_snapshots: list[dict[str, typing.Any]],
) -> int:
    """Merge insight snapshots onto SubscriptionDelivery.content_snapshot.

    Returns the serialized size of the insight_snapshots payload so callers can
    log it — the whole point of owning this write is staying under size cliffs,
    so measuring proximity to the next one is worth the cycles.
    """
    snapshot_bytes = len(json.dumps(insight_snapshots, default=str).encode("utf-8"))

    @database_sync_to_async(thread_sensitive=False)
    def _merge() -> None:
        delivery = SubscriptionDelivery.objects.get(pk=delivery_id)
        # insight_snapshots must already be NUL-scrubbed at its source (build_insight_delivery_snapshot
        # → _serialize_insight_result); a NUL reaching content_snapshot fails this save with a DataError.
        delivery.content_snapshot = {
            **(delivery.content_snapshot or {}),
            "total_insight_count": total_insight_count,
            "insights": insight_snapshots,
        }
        delivery.save(update_fields=["content_snapshot", "last_updated_at"])

    await _merge()
    return snapshot_bytes


@temporalio.activity.defn
async def fetch_due_subscriptions_activity(inputs: FetchDueSubscriptionsActivityInputs) -> list[DueSubscription]:
    now_with_buffer = dt.datetime.now(dt.UTC) + dt.timedelta(minutes=inputs.buffer_minutes)
    await LOGGER.ainfo("Fetching due subscriptions", deadline=now_with_buffer)

    @database_sync_to_async(thread_sensitive=False)
    def get_subscriptions() -> list[DueSubscription]:
        return [
            DueSubscription(
                subscription_id=sub["id"],
                team_id=sub["team_id"],
                distinct_id=str(sub["created_by__distinct_id"])
                if sub["created_by__distinct_id"]
                else str(sub["team_id"]),
                next_delivery_date=sub["next_delivery_date"].isoformat() if sub["next_delivery_date"] else None,
                resource_type=Subscription.derive_resource_type(sub["insight_id"], sub["dashboard_id"], sub["prompt"]),
            )
            for sub in Subscription.objects.filter(next_delivery_date__lte=now_with_buffer, deleted=False, enabled=True)
            .exclude(dashboard__deleted=True)
            .exclude(insight__deleted=True)
            # Skip relationless subs — derive_resource_type raises on them, and one bad row would fail the whole batch.
            .exclude(
                Q(insight_id__isnull=True) & Q(dashboard_id__isnull=True) & (Q(prompt__isnull=True) | Q(prompt=""))
            )
            .values(
                "id", "team_id", "created_by__distinct_id", "next_delivery_date", "insight_id", "dashboard_id", "prompt"
            )
        ]

    subscriptions = await get_subscriptions()
    await LOGGER.ainfo("Fetched due subscriptions", count=len(subscriptions))

    return subscriptions


@temporalio.activity.defn
async def validate_subscription_for_delivery(subscription_id: int) -> DeliveryAbort | None:
    """Returns abort info when delivery should not proceed; None to continue."""
    subscription = await database_sync_to_async(
        Subscription.objects.select_related("created_by", "integration").get,
        thread_sensitive=False,
    )(pk=subscription_id)

    # Idempotency: a Temporal redispatch (e.g. worker crash mid-acknowledge) after a
    # prior auto-disable committed must not re-fire side effects.
    if not subscription.enabled:
        await LOGGER.ainfo("validate_subscription.already_disabled_skipping", subscription_id=subscription_id)
        return DeliveryAbort()

    reason = get_subscription_disable_reason(subscription.target_type, subscription.integration_id)
    if reason is None:
        return None

    LOGGER.warning(
        "validate_subscription.invalid_auto_disabling",
        subscription_id=subscription_id,
        target_type=subscription.target_type,
        reason=reason.key,
    )
    _capture_delivery_failed_event(subscription, Exception(reason.description))
    await database_sync_to_async(disable_invalid_subscription, thread_sensitive=False)(subscription, reason)
    return DeliveryAbort(
        failed_recipient=RecipientResult(
            recipient=subscription.recipient_label,
            status="failed",
            error={"message": reason.description, "type": reason.key},
            human_readable_error=reason.description,
        )
    )


@temporalio.activity.defn
async def create_export_assets(inputs: CreateExportAssetsInputs) -> CreateExportAssetsResult:
    await LOGGER.ainfo(
        "create_export_assets.starting",
        subscription_id=inputs.subscription_id,
    )

    max_asset_count = inputs.max_asset_count if inputs.max_asset_count is not None else MAX_INSIGHTS
    if max_asset_count <= 0:
        raise ApplicationError(
            f"Dashboard insight export limit must be at least 1, received {max_asset_count} for subscription {inputs.subscription_id}",
            non_retryable=True,
        )

    subscription = await database_sync_to_async(
        Subscription.objects.select_related("created_by", "insight", "dashboard", "team").get,
        thread_sensitive=False,
    )(pk=inputs.subscription_id)

    team = subscription.team
    dashboard = subscription.dashboard

    await LOGGER.ainfo(
        "create_export_assets.loaded",
        subscription_id=inputs.subscription_id,
        has_dashboard=bool(dashboard),
        has_insight=bool(subscription.insight_id),
        target_type=subscription.target_type,
    )

    resolved_insights = await _resolve_exportable_insights(subscription)
    tile_insight_pairs = resolved_insights.tile_insight_pairs

    total_insight_count = len(tile_insight_pairs)

    if not tile_insight_pairs:
        no_exportable_reason = resolved_insights.no_exportable_reason
        if no_exportable_reason is None:
            raise RuntimeError("No-exportable-insights resolution missing a failure reason")
        failure_context: NoExportableInsightsContext = {
            "reason": no_exportable_reason,
            "resource_type": "dashboard" if dashboard else "insight" if subscription.insight_id else "unknown",
            "available_insight_count": resolved_insights.available_insight_count,
            "selected_insight_count": resolved_insights.selected_insight_count,
        }
        await LOGGER.awarning(
            "create_export_assets.no_exportable_insights",
            subscription_id=inputs.subscription_id,
            dashboard_id=subscription.dashboard_id,
            insight_id=subscription.insight_id,
            **failure_context,
        )
        _capture_delivery_failed_event(
            subscription,
            NoExportableInsightsError(no_exportable_reason),
            failure_context,
        )
        return CreateExportAssetsResult(
            exported_asset_ids=[],
            total_insight_count=total_insight_count,
            team_id=team.id,
            distinct_id=str(subscription.created_by.distinct_id) if subscription.created_by else str(team.id),
            target_type=subscription.target_type,
            available_insight_count=resolved_insights.available_insight_count,
            selected_insight_count=resolved_insights.selected_insight_count,
            insight_limit=max_asset_count,
            status=ExportAssetPreparationStatus.NO_EXPORTABLE_INSIGHTS,
            failure_context=failure_context,
        )

    export_pairs = tile_insight_pairs[:max_asset_count]

    expiry = ExportedAsset.compute_expires_after(ExportedAsset.ExportFormat.PNG)
    assets = [
        ExportedAsset(
            team=team,
            export_format=ExportedAsset.ExportFormat.PNG,
            insight=insight,
            dashboard=dashboard,
            expires_after=expiry,
            # The exporter runs the insight query as the asset's creator; without it the render is
            # userless and warehouse access control fails closed, breaking subscription deliveries.
            created_by=subscription.created_by,
        )
        for _tile, insight in export_pairs
    ]
    await database_sync_to_async(ExportedAsset.objects.bulk_create, thread_sensitive=False)(assets)

    @database_sync_to_async(thread_sensitive=False)
    def build_insight_snapshots() -> list[dict[str, typing.Any]]:
        return [
            build_insight_delivery_snapshot(
                insight=insight,
                team=team,
                dashboard=dashboard,
                tile=tile,
                user=subscription.created_by,
            )
            for tile, insight in export_pairs
        ]

    insight_snapshots = await build_insight_snapshots()

    # Persist insight snapshots directly on SubscriptionDelivery.content_snapshot
    # instead of returning them across the Temporal activity boundary — per-insight
    # query_results can reach multi-MB and will trip Temporal's ~2 MiB payload cap.
    # Standalone callers (tests, management commands) that don't pass delivery_id
    # skip the persist — they don't have a row to write to.
    target_delivery_id = inputs.delivery_id
    if target_delivery_id is not None:
        snapshot_bytes = await _persist_content_snapshot(
            delivery_id=target_delivery_id,
            total_insight_count=total_insight_count,
            insight_snapshots=insight_snapshots,
        )
        await LOGGER.ainfo(
            "create_export_assets.content_snapshot_persisted",
            subscription_id=inputs.subscription_id,
            delivery_id=str(target_delivery_id),
            insight_count=len(insight_snapshots),
            snapshot_bytes=snapshot_bytes,
        )

    await LOGGER.ainfo(
        "create_export_assets.assets_created",
        subscription_id=inputs.subscription_id,
        asset_count=len(assets),
        total_insights=total_insight_count,
    )
    return CreateExportAssetsResult(
        exported_asset_ids=[a.id for a in assets],
        total_insight_count=total_insight_count,
        team_id=team.id,
        distinct_id=str(subscription.created_by.distinct_id) if subscription.created_by else str(team.id),
        target_type=subscription.target_type,
        available_insight_count=resolved_insights.available_insight_count,
        selected_insight_count=resolved_insights.selected_insight_count,
        insight_limit=max_asset_count,
    )


def _downgrade_for_unrendered_assets(
    result: DeliverSubscriptionResult, unrendered_count: int, total_count: int
) -> DeliverSubscriptionResult:
    """A destination that accepts the message is not a delivered chart. Without this, a
    subscription whose insights all failed to render is still recorded as a success."""
    message = f"{unrendered_count} of {pluralize(total_count, 'insight')} could not be generated"
    all_unrendered = unrendered_count == total_count
    status: RecipientResultStatus = "failed" if all_unrendered else "partial"
    # With no chart rendered, a partial result (such as a failed Slack thread message) delivered nothing either.
    downgradable: set[RecipientResultStatus] = {"success", "partial"} if all_unrendered else {"success"}
    downgraded = [
        RecipientResult(
            recipient=recipient_result.recipient,
            status=status,
            error={"message": message, "type": "unrendered_assets"},
            human_readable_error=message,
        )
        if recipient_result.status in downgradable
        else recipient_result
        for recipient_result in result.recipient_results
    ]
    return dataclasses.replace(result, recipient_results=downgraded)


@temporalio.activity.defn
async def deliver_subscription(inputs: DeliverSubscriptionInputs) -> DeliverSubscriptionResult:
    # TODO(2026-07-31): After workflows started before 2026-07-31 have drained, remove this v1 activity,
    # rename deliver_subscription_v2 to deliver_subscription, and remove the workflow patch.
    return await _deliver_subscription(inputs)


@temporalio.activity.defn(name="deliver-subscription-v2")
async def deliver_subscription_v2(inputs: DeliverSubscriptionInputs) -> DeliverSubscriptionResult:
    return await _deliver_subscription(inputs)


async def _deliver_subscription(inputs: DeliverSubscriptionInputs) -> DeliverSubscriptionResult:
    recipient_results: list[RecipientResult] = []

    subscription = await database_sync_to_async(
        Subscription.objects.select_related("created_by", "insight", "dashboard", "team", "integration").get,
        thread_sensitive=False,
    )(pk=inputs.subscription_id)

    # Activity-retry idempotency: if a previous attempt already auto-disabled this
    # subscription (UPDATE committed) and Temporal redispatched the activity (e.g.
    # worker crash mid-acknowledge), don't re-fire the disable side effects — UUID4
    # campaign keys mean MessagingRecord wouldn't dedup the duplicate email.
    if not subscription.enabled:
        LOGGER.info("deliver_subscription.skipped_disabled", subscription_id=inputs.subscription_id)
        return DeliverSubscriptionResult(recipient_results=[])

    previous_target_value = inputs.previous_target_value
    if previous_target_value is None:
        previous_target_value = inputs.previous_value
    send_only_to_new_recipients = (
        inputs.is_new_subscription_target
        if inputs.is_new_subscription_target is not None
        else previous_target_value is not None and previous_target_value != subscription.target_value
    )

    await LOGGER.ainfo(
        "deliver_subscription.starting",
        subscription_id=inputs.subscription_id,
        target_type=subscription.target_type,
        asset_count=len(inputs.exported_asset_ids),
        is_new=send_only_to_new_recipients,
        resource_type=subscription.resource_type,
    )

    if subscription.resource_type == Subscription.ResourceType.AI_PROMPT:
        return await _deliver_ai_subscription(subscription, inputs, recipient_results)

    return await _deliver_insight_dashboard_subscription(
        subscription, inputs, recipient_results, send_only_to_new_recipients
    )


async def _deliver_insight_dashboard_subscription(
    subscription: Subscription,
    inputs: DeliverSubscriptionInputs,
    recipient_results: list[RecipientResult],
    send_only_to_new_recipients: bool,
) -> DeliverSubscriptionResult:
    if (
        get_subscription_disable_reason(subscription.target_type, subscription.integration_id)
        == UNSUPPORTED_TARGET_DISABLE_REASON
    ):
        LOGGER.warning(
            "deliver_subscription.unsupported_target",
            subscription_id=inputs.subscription_id,
            target_type=subscription.target_type,
        )
        return await auto_disable_and_return(
            subscription,
            UNSUPPORTED_TARGET_DISABLE_REASON,
            recipient_results,
        )

    assets_by_id = await database_sync_to_async(
        lambda: {
            a.id: a
            for a in ExportedAsset.objects_including_ttl_deleted.select_related("insight", "dashboard").filter(
                pk__in=inputs.exported_asset_ids
            )
        },
        thread_sensitive=False,
    )()
    # Preserve the order from create_export_assets (sorted by dashboard tile layout)
    assets = [assets_by_id[aid] for aid in inputs.exported_asset_ids if aid in assets_by_id]

    if not assets:
        # Empty here means non-empty exported_asset_ids didn't resolve from DB — a
        # transient condition (TTL sweep, prior export crash, S3 race). Genuine
        # deletion is filtered upstream in create_export_assets and the workflow
        # short-circuits to SKIPPED before this activity runs. Don't auto-disable;
        # the failure is observable via the `subscription_delivery_failed` analytics
        # event and the next scheduled delivery retries.
        LOGGER.warning("deliver_subscription.no_assets", subscription_id=inputs.subscription_id)
        recipient_results.append(
            RecipientResult(
                recipient=subscription.recipient_label,
                status="failed",
                error={"message": NO_ASSETS_REASON, "type": "no_assets"},
                human_readable_error=NO_ASSETS_HUMAN_READABLE_REASON,
            )
        )
        # Plain Exception — `_capture_delivery_failed_event` only reads `str(e)` and
        # `type(e).__name__`, and the activity returns cleanly so retry semantics on
        # ApplicationError would be misleading (matches `_auto_disable_and_return`).
        _capture_delivery_failed_event(subscription, Exception(NO_ASSETS_REASON))
        return DeliverSubscriptionResult(recipient_results=recipient_results)

    # The failed tiles in this delivery already tell the recipients why, so nobody else gets an email.
    disable_reason = get_assets_owner_disable_reason(asset.exception_type for asset in assets)

    try:
        result = await _send_to_target(subscription, inputs, assets, recipient_results, send_only_to_new_recipients)
    except Exception as error:
        # Temporal retries every failure but a non-retryable one, so the retry delivers the reason
        # and the row stays enabled until it does.
        if not (isinstance(error, ApplicationError) and error.non_retryable):
            disable_reason = None
        raise
    finally:
        if disable_reason is not None:
            await database_sync_to_async(disable_invalid_subscription, thread_sensitive=False)(
                subscription, disable_reason, notify_owner=False
            )

    unrendered_assets = [asset for asset in assets if _has_asset_failed(asset)]
    if unrendered_assets:
        downgraded = _downgrade_for_unrendered_assets(result, len(unrendered_assets), len(assets))
        # Only a result this step turned to failed needs the event. Paths that failed earlier already captured one.
        if any(
            before.status != "failed" and after.status == "failed"
            for before, after in zip(result.recipient_results, downgraded.recipient_results)
        ):
            _capture_delivery_failed_event(subscription, Exception(ASSET_GENERATION_FAILED_MESSAGE))
        result = downgraded

    await LOGGER.ainfo(
        "deliver_subscription.completed",
        subscription_id=inputs.subscription_id,
        target_type=subscription.target_type,
        unrendered_asset_count=len(unrendered_assets),
    )
    return result


async def _send_to_target(
    subscription: Subscription,
    inputs: DeliverSubscriptionInputs,
    assets: list[ExportedAsset],
    recipient_results: list[RecipientResult],
    send_only_to_new_recipients: bool,
) -> DeliverSubscriptionResult:
    """Send the assets over the subscription's channel. Split out so the caller can wrap the one send."""
    if subscription.target_type == Subscription.SubscriptionTarget.EMAIL:

        async def _send_email(email: str) -> None:
            await database_sync_to_async(send_email_subscription_report, thread_sensitive=False)(
                email,
                subscription,
                assets,
                invite_message=inputs.invite_message or "" if send_only_to_new_recipients else None,
                total_asset_count=inputs.total_insight_count,
                send_async=False,
                change_summary=inputs.change_summary,
                summary_skipped_over_budget=inputs.summary_skipped_over_budget,
                delivery_id=inputs.delivery_id,
            )

        result = await deliver_email(subscription, inputs, recipient_results, _send_email)
    elif subscription.target_type == Subscription.SubscriptionTarget.SLACK:
        result = await deliver_slack(
            subscription,
            recipient_results,
            lambda integration: send_slack_message_with_integration_async(
                integration,
                subscription,
                assets,
                total_asset_count=inputs.total_insight_count,
                is_new_subscription=send_only_to_new_recipients,
                change_summary=inputs.change_summary,
                summary_skipped_over_budget=inputs.summary_skipped_over_budget,
            ),
        )
    elif subscription.target_type == Subscription.SubscriptionTarget.TEAMS:
        card = build_teams_subscription_card(
            subscription,
            assets,
            inputs.total_insight_count,
            is_new_subscription=send_only_to_new_recipients,
            change_summary=inputs.change_summary,
            summary_skipped_over_budget=inputs.summary_skipped_over_budget,
        )
        result = await deliver_teams_webhook(subscription, recipient_results, body=card)
    else:
        raise ApplicationError(
            f"Subscription delivery reached an unsupported target {subscription.target_type!r}",
            non_retryable=True,
        )
    return result


@temporalio.activity.defn
async def create_delivery_record(inputs: CreateDeliveryRecordInputs) -> uuid.UUID:
    scheduled_at = datetime.fromisoformat(inputs.scheduled_at) if inputs.scheduled_at else None

    @database_sync_to_async(thread_sensitive=False)
    def _create() -> uuid.UUID:
        subscription = Subscription.objects.select_related("insight", "dashboard").get(pk=inputs.subscription_id)
        if subscription.team_id != inputs.team_id:
            raise ValueError(
                f"Subscription team_id ({subscription.team_id}) does not match inputs.team_id ({inputs.team_id})"
            )

        content_snapshot = build_initial_content_snapshot(subscription)
        context_refs = sorted(
            context.ref
            for context in SubscriptionContext.objects.for_team(subscription.team_id).filter(subscription=subscription)
        )

        delivery, _created = SubscriptionDelivery.objects.get_or_create(
            idempotency_key=inputs.idempotency_key,
            defaults={
                "subscription": subscription,
                "team_id": inputs.team_id,
                "temporal_workflow_id": inputs.temporal_workflow_id,
                "trigger_type": inputs.trigger_type,
                "scheduled_at": scheduled_at,
                "target_type": subscription.target_type,
                "target_value": subscription.recipient_label,
                "content_snapshot": content_snapshot,
                "context_refs": context_refs,
                "status": SubscriptionDelivery.Status.STARTING,
            },
        )
        return delivery.id

    delivery_id = await _create()
    await LOGGER.ainfo(
        "create_delivery_record.created",
        subscription_id=inputs.subscription_id,
        delivery_id=delivery_id,
    )
    return delivery_id


@temporalio.activity.defn
async def update_delivery_record(inputs: UpdateDeliveryRecordInputs) -> None:
    @database_sync_to_async(thread_sensitive=False)
    def _update() -> None:
        delivery = SubscriptionDelivery.objects.get(pk=inputs.delivery_id)
        update_fields: list[str] = ["status", "last_updated_at"]
        delivery.status = inputs.status

        if inputs.exported_asset_ids is not None:
            delivery.exported_asset_ids = inputs.exported_asset_ids
            update_fields.append("exported_asset_ids")
        if inputs.recipient_results is not None:
            delivery.recipient_results = inputs.recipient_results
            update_fields.append("recipient_results")
        if inputs.change_summary is not None:
            delivery.change_summary = inputs.change_summary
            update_fields.append("change_summary")
        delivery.error = inputs.error
        update_fields.append("error")
        if inputs.finished:
            delivery.finished_at = tz.now()
            update_fields.append("finished_at")

        delivery.save(update_fields=update_fields)

    await _update()
    await LOGGER.ainfo(
        "update_delivery_record.updated",
        delivery_id=inputs.delivery_id,
        status=inputs.status,
    )


@temporalio.activity.defn
async def notify_subscription_delivery_failure(subscription_id: int, failure_id: str) -> None:
    subscription = await database_sync_to_async(
        Subscription.objects.select_related("created_by").get,
        thread_sensitive=False,
    )(pk=subscription_id)
    errors: list[Exception] = []
    try:
        await database_sync_to_async(send_subscription_delivery_failure_email, thread_sensitive=False)(
            subscription, failure_id
        )
    except Exception as error:
        errors.append(error)
        LOGGER.exception("notify_subscription_delivery_failure.email_failed", subscription_id=subscription_id)

    try:
        await database_sync_to_async(create_subscription_delivery_failure_notification, thread_sensitive=False)(
            subscription, failure_id
        )
    except Exception as error:
        errors.append(error)
        LOGGER.exception(
            "notify_subscription_delivery_failure.in_app_notification_failed", subscription_id=subscription_id
        )

    if errors:
        raise errors[0]


@temporalio.activity.defn
async def advance_next_delivery_date(subscription_id: int) -> None:
    subscription = await database_sync_to_async(Subscription.objects.get, thread_sensitive=False)(pk=subscription_id)
    # Disabled subs (e.g. auto-disabled this run / paused by user) don't get a
    # future delivery date — avoids showing a misleading "next delivery" in the UI.
    if not subscription.enabled:
        await LOGGER.ainfo("advance_next_delivery_date.skipped_disabled", subscription_id=subscription_id)
        return
    subscription.set_next_delivery_date(subscription.next_delivery_date)
    await database_sync_to_async(subscription.save, thread_sensitive=False)(update_fields=["next_delivery_date"])
    await LOGGER.ainfo(
        "advance_next_delivery_date.updated",
        subscription_id=subscription_id,
        next_delivery_date=subscription.next_delivery_date,
    )