: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(signals): email the activator when their first report is ready (#119762)
Georgiy Tarasov7d3099e466b6
diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yamlindex 19519f4c9b6b..040b5e813bf2 100644--- a/.semgrep/rules/security/idor-team-scoped-models.yaml+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml@@ -379,6 +379,7 @@ rules:|SessionRecordingPlaylist|SharingConfiguration|SignalEmissionRecord+ |SignalFirstReportNotification|SignalReport|SignalReportAction|SignalReportArtefact@@ -841,6 +842,7 @@ rules:|SessionRecordingPlaylist|SharingConfiguration|SignalEmissionRecord+ |SignalFirstReportNotification|SignalReport|SignalReportAction|SignalReportArtefact@@ -1178,6 +1180,7 @@ rules:|SessionRecordingViewed|SharingConfiguration|SignalEmissionRecord+ |SignalFirstReportNotification|SignalReport|SignalReportArtefact|SignalReportCheckdiff --git a/posthog/tasks/scheduled.py b/posthog/tasks/scheduled.pyindex 96dea56cb627..d4cbf2a905cc 100644--- a/posthog/tasks/scheduled.py+++ b/posthog/tasks/scheduled.py@@ -122,6 +122,7 @@ from products.signals.backend.tasks import (prune_expired_scratchpad_entries_task,refresh_signal_repository_activity,refresh_signal_scout_background_bands,+ sweep_first_report_notifications,sweep_implementation_dispatches,sync_pending_signals_refund_credits,)@@ -439,6 +440,14 @@ def setup_periodic_tasks(sender: Celery, **kwargs: Any) -> None:expires_seconds=5 * 60,)+ add_periodic_task_with_expiry(+ sender,+ crontab(minute="*/5"),+ sweep_first_report_notifications.s(),+ name="send first self-driving report emails",+ expires_seconds=5 * 60,+ )+# Re-enqueue signals PR refunds whose billing credit sync hasn't landed - hourly at minute 25sender.add_periodic_task(crontab(hour="*", minute="25"),diff --git a/posthog/test/repo_invariants/setup_receivers_baseline.txt b/posthog/test/repo_invariants/setup_receivers_baseline.txtindex 1ba7b5aff833..a1556ace9ef5 100644--- a/posthog/test/repo_invariants/setup_receivers_baseline.txt+++ b/posthog/test/repo_invariants/setup_receivers_baseline.txt@@ -237,6 +237,7 @@ post_save:products.signals.backend.receivers.arm_pending_checks_when_report_resopost_save:products.signals.backend.receivers.capture_status_change_analyticspost_save:products.signals.backend.receivers.close_pr_when_report_dismissedpost_save:products.signals.backend.receivers.emit_report_embedding_on_document_change+post_save:products.signals.backend.receivers.enqueue_first_report_notificationpost_save:products.signals.backend.receivers.mark_scout_suggestions_stale_on_fleet_changepost_save:products.signals.backend.receivers.push_report_to_reviewers_when_first_visiblepost_save:products.signals.backend.receivers.reconcile_report_embedding_on_verdict_saveddiff --git a/products/signals/ARCHITECTURE.md b/products/signals/ARCHITECTURE.mdindex 2312e4a3f77c..31dc1ea5dda9 100644--- a/products/signals/ARCHITECTURE.md+++ b/products/signals/ARCHITECTURE.md@@ -236,6 +236,16 @@ On re-promotion:- **Auto-start is deduplicated per report** by a legacy `SignalReportTask` implementation link (alongside the protected `task_run` log), checked inside the report-row `select_for_update`- **Workflow ID** includes `run_count` on reruns to avoid Temporal ID collisions with earlier executions+#### First report email++Guided and quick onboarding create a `SignalFirstReportNotification` in the activation transaction, preserving the activating user for that environment. The first report that becomes `ready`, immediately actionable, and not already addressed after activation triggers a transactional email to that user's email address, tracked against their distinct ID. Control onboarding does not identify an activator and does not enroll a recipient.++Sending requires the organization-scoped `signals-first-report-email` feature flag and is cloud-only. A disabled, missing, or unavailable flag leaves notifications pending without claiming or cancelling them, including in DEBUG. Sending also remains disabled until the dedicated `POSTHOG_TRANSACTIONAL_EMAIL_API_KEY` is configured. `SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID` in `backend/constants.py` selects the first-report transactional email template. The shared `POSTHOG_PROJECT_ID` and `POSTHOG_HOST` settings default to `2` and `https://us.posthog.com`, independently of the recipient's region. Both support optional environment overrides to select another sending project or host. The API key must be a project secret API key with `hog_flow:write` for that sending project, and the template must be an active transactional email template with a verified sender. Sending uses the shared transactional email client synchronously inside the notification task so the notification row can record the API's acceptance. Template creation and deployment configuration are separate from this code. The template can use `{{ variables.project_id }}`, `{{ variables.report_id }}`, `{{ variables.report_title }}`, `{{ variables.report_url }}`, and `{{ variables.activation_id }}`. All template data is supplied explicitly; the recipient need not have a person profile in the sending project.++Report and actionability writes enqueue delivery on the Celery `email` queue after commit. A sweep on the default Celery queue runs every five minutes to recover missed enqueues and retry confirmed rejections. The sweep skips database queries and task fan-out when cloud delivery or the shared sender configuration is disabled. A `Retry-After` response sets `next_attempt_at`; both delivery claims and the sweep respect that deadline, and the Celery retry uses the same delay. Delivery rechecks report visibility, organization membership, project access, and report access, and never substitutes another recipient. The selected report and template data persist across retries. A selected report undergoing research stays pending until it becomes visible again. `queued_at` and `message_id` record acceptance by the transactional pipeline, not delivery to the recipient's mailbox. Sending does not wait for implementation or Slack notification delivery.++The transactional send API has no idempotency key. `send_started_at` is committed before the send, so concurrent workers, uncertain responses, and worker loss cannot automatically queue a duplicate. Confirmed pre-send failures, quota rejections, and connection timeouts clear that marker and can retry. A row with `send_started_at` set and `queued_at` unset requires reconciliation against the sending project's workflow history before retrying: record the accepted message if found, or clear the marker only after confirming nothing was queued. A crash before the request can also leave such a row. Uncertain outcomes are held rather than retried automatically.+### `SignalReportReingestionWorkflow` (`signal-report-reingestion`)Deletes a report and re-ingests its signals through the current Signals ingestion pipeline. Useful when grouping decisions need to be re-evaluated after prompt or matching changes.diff --git a/products/signals/backend/constants.py b/products/signals/backend/constants.pynew file mode 100644index 000000000000..06cf3439b86f--- /dev/null+++ b/products/signals/backend/constants.py@@ -0,0 +1 @@+SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID: str = "01a1598d-9186-0000-b20d-d91813fc05ff"diff --git a/products/signals/backend/facade/onboarding.py b/products/signals/backend/facade/onboarding.pyindex 3fe40c694f42..50bc43ffac94 100644--- a/products/signals/backend/facade/onboarding.py+++ b/products/signals/backend/facade/onboarding.py@@ -13,6 +13,7 @@ from posthog.models.team.team import Teamfrom posthog.models.user import Userfrom products.replay_vision.backend.facade.api import signal_emitting_scanner_ids+from products.signals.backend.first_report_notification import register_first_report_notificationfrom products.signals.backend.models import (AutonomyPriority,SignalScoutConfig,@@ -203,6 +204,7 @@ class InboxOnboarding:config.save(update_fields=["onboarding", "autostart_enabled", "default_autostart_priority", "updated_at"])+ register_first_report_notification(team=self.team, user=user)if resume_operational_scouts:InboxOnboardingScouts.resume(scout_team_id, withheld, lambda: self.authorize_scouts(True))transaction.on_commit(lambda: self._report_completion(user, config), robust=True)diff --git a/products/signals/backend/first_report_notification.py b/products/signals/backend/first_report_notification.pynew file mode 100644index 000000000000..68658451c448--- /dev/null+++ b/products/signals/backend/first_report_notification.py@@ -0,0 +1,152 @@+from __future__ import annotations++from datetime import timedelta+from typing import TYPE_CHECKING++from django.core.exceptions import ImproperlyConfigured+from django.db import transaction+from django.db.models import Q+from django.utils import timezone++import structlog++from posthog.cloud_utils import is_cloud+from posthog.models import Team+from posthog.transactional_email import (+ TransactionalEmailRejected,+ TransactionalEmailRetryableError,+ is_transactional_email_configured,+ send_transactional_email,+)+from posthog.utils import absolute_uri++from products.access_control.backend.facade.user_access_control import UserAccessControl+from products.signals.backend.artefact_schemas import ActionabilityChoice+from products.signals.backend.constants import SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID+from products.signals.backend.models import SignalFirstReportNotification, SignalReport+from products.signals.backend.report_access import may_read_reports+from products.signals.backend.report_content_gates import team_first_report_email_enabled++if TYPE_CHECKING:+ from django.db.models import QuerySet++ from posthog.models import User++logger = structlog.get_logger(__name__)+++def register_first_report_notification(*, team: Team, user: User) -> None:+ SignalFirstReportNotification.objects.for_team(team.id).get_or_create(+ team_id=team.id, defaults={"activated_by": user}+ )+++def _eligible_recipient(user: User | None, team: Team) -> bool:+ return bool(+ user+ and user.is_active+ and user.email+ and user.distinct_id+ and team.organization.members.filter(pk=user.pk).exists()+ and UserAccessControl(user=user, team=team).has_project_access+ and may_read_reports(user=user, team=team)+ )+++def _visible_reports(team_id: int) -> QuerySet[SignalReport]:+ return (+ SignalReport.objects.filter(+ team_id=team_id,+ status=SignalReport.Status.READY,+ latest_actionability=ActionabilityChoice.IMMEDIATELY_ACTIONABLE.value,+ latest_already_addressed=False,+ )+ .exclude(title="")+ .exclude(summary="")+ )+++def _claim(team_id: int) -> SignalFirstReportNotification | None:+ with transaction.atomic():+ notification = (+ SignalFirstReportNotification.objects.for_team(team_id)+ .select_for_update(of=("self",))+ .select_related("team__organization", "activated_by")+ .filter(queued_at__isnull=True, cancelled_at__isnull=True, send_started_at__isnull=True)+ .filter(Q(next_attempt_at__isnull=True) | Q(next_attempt_at__lte=timezone.now()))+ .first()+ )+ if notification is None:+ return None+ if not _eligible_recipient(notification.activated_by, notification.team):+ notification.cancelled_at = timezone.now()+ notification.save(update_fields=["cancelled_at"])+ return None+ reports = _visible_reports(team_id).filter(first_visible_at__gte=notification.activated_at)+ if notification.message_data:+ report = reports.filter(id=notification.report_id).first() if notification.report_id else None+ else:+ report = reports.order_by("first_visible_at", "id").first()+ if report is None:+ if notification.message_data and (+ notification.report_id is None+ or not SignalReport.objects.filter(+ team_id=team_id,+ id=notification.report_id,+ status__in=[+ SignalReport.Status.CANDIDATE,+ SignalReport.Status.IN_PROGRESS,+ SignalReport.Status.PENDING_INPUT,+ ],+ ).exists()+ ):+ notification.cancelled_at = timezone.now()+ notification.save(update_fields=["cancelled_at"])+ return None+ if notification.report_id is None:+ notification.report = report+ notification.message_data = {+ "project_id": team_id,+ "report_id": str(report.id),+ "report_title": report.title,+ "report_url": absolute_uri(f"/project/{team_id}/inbox/reports/{report.id}"),+ "activation_id": str(notification.id),+ }+ # The transactional API has no idempotency key. A crash or uncertain response must leave+ # this marker intact, because another send could duplicate an email already queued.+ notification.send_started_at = timezone.now()+ notification.next_attempt_at = None+ notification.last_error = ""+ notification.save(update_fields=["report", "message_data", "send_started_at", "next_attempt_at", "last_error"])+ return notification+++def deliver_first_report_email(team_id: int) -> None:+ if not is_cloud() or not is_transactional_email_configured() or not team_first_report_email_enabled(team_id):+ return+ notification = _claim(team_id)+ if notification is None:+ return+ assert notification.activated_by is not None+ record = SignalFirstReportNotification.objects.for_team(team_id).filter(pk=notification.pk)+ try:+ message_id = send_transactional_email(+ SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID,+ to=notification.activated_by.email,+ distinct_id=str(notification.activated_by.distinct_id),+ message_data=notification.message_data,+ )+ except (TransactionalEmailRetryableError, TransactionalEmailRejected, ImproperlyConfigured) as error:+ # These failures occur before the workflow accepts a send, so they can safely retry.+ retry_after = error.retry_after if isinstance(error, TransactionalEmailRetryableError) else None+ record.update(+ send_started_at=None,+ next_attempt_at=timezone.now() + timedelta(seconds=retry_after) if retry_after is not None else None,+ last_error="setup_error" if isinstance(error, ImproperlyConfigured) else str(error),+ )+ raise+ except Exception:+ record.update(last_error="delivery_uncertain")+ logger.exception("first_report_email_delivery_uncertain", notification_id=str(notification.id))+ raise+ record.update(queued_at=timezone.now(), message_id=message_id)diff --git a/products/signals/backend/first_report_notification_tasks.py b/products/signals/backend/first_report_notification_tasks.pynew file mode 100644index 000000000000..078fd3fd284d--- /dev/null+++ b/products/signals/backend/first_report_notification_tasks.py@@ -0,0 +1,64 @@+from django.db.models import Q+from django.utils import timezone++from celery import Task, shared_task++from posthog.celery_queues import CeleryQueue+from posthog.cloud_utils import is_cloud+from posthog.exceptions_capture import capture_exception+from posthog.models.scoping import with_team_scope+from posthog.scoping_audit import skip_team_scope_audit+from posthog.transactional_email import TransactionalEmailRetryableError, is_transactional_email_configured++from products.signals.backend.first_report_notification import deliver_first_report_email+from products.signals.backend.models import SignalFirstReportNotification+++@shared_task(+ bind=True,+ queue=CeleryQueue.EMAIL.value,+ ignore_result=True,+ autoretry_for=(Exception,),+ retry_backoff=True,+ max_retries=5,+ soft_time_limit=210,+ time_limit=240,+ acks_late=True,+ reject_on_worker_lost=True,+)+@with_team_scope()+def dispatch_first_report_notification(self: Task, team_id: int) -> None:+ try:+ deliver_first_report_email(team_id)+ except Exception as error:+ capture_exception(error)+ if isinstance(error, TransactionalEmailRetryableError) and error.retry_after is not None:+ raise self.retry(exc=error, countdown=error.retry_after)+ raise+++def _sweep_first_report_notifications(after_id: str | None) -> None:+ if not is_cloud() or not is_transactional_email_configured():+ return+ pending = (+ SignalFirstReportNotification.objects.unscoped()+ .filter(queued_at__isnull=True, cancelled_at__isnull=True, send_started_at__isnull=True)+ .filter(Q(next_attempt_at__isnull=True) | Q(next_attempt_at__lte=timezone.now()))+ )+ if after_id:+ pending = pending.filter(id__gt=after_id)+ page = list(pending.order_by("id").values_list("id", "team_id")[:500])+ for _, team_id in page:+ dispatch_first_report_notification.delay(team_id)+ if len(page) == 500:+ sweep_first_report_notifications.delay(str(page[-1][0]))+++@shared_task(ignore_result=True)+@skip_team_scope_audit+def sweep_first_report_notifications(after_id: str | None = None) -> None:+ try:+ _sweep_first_report_notifications(after_id)+ except Exception as error:+ capture_exception(error)+ raisediff --git a/products/signals/backend/migrations/0189_first_report_notification.py b/products/signals/backend/migrations/0189_first_report_notification.pynew file mode 100644index 000000000000..fe0e0894e308--- /dev/null+++ b/products/signals/backend/migrations/0189_first_report_notification.py@@ -0,0 +1,81 @@+# Generated by Django 5.2.18 on 2026-10-19 16:53++import django.db.models.deletion+from django.conf import settings+from django.db import migrations, models++import posthog.uuidt+++class Migration(migrations.Migration):+ dependencies = [+ ("posthog", "1401_drop_userproductlist_table"),+ ("signals", "0188_useractivitysummary_skipped_status"),+ migrations.swappable_dependency(settings.AUTH_USER_MODEL),+ ]++ operations = [+ migrations.CreateModel(+ name="SignalFirstReportNotification",+ fields=[+ (+ "id",+ models.UUIDField(+ default=posthog.uuidt.uuid7,+ editable=False,+ primary_key=True,+ serialize=False,+ ),+ ),+ ("activated_at", models.DateTimeField(auto_now_add=True)),+ ("message_data", models.JSONField(db_default={}, default=dict)),+ ("send_started_at", models.DateTimeField(blank=True, null=True)),+ ("next_attempt_at", models.DateTimeField(blank=True, null=True)),+ ("queued_at", models.DateTimeField(blank=True, null=True)),+ ("message_id", models.CharField(blank=True, max_length=200, null=True)),+ ("last_error", models.CharField(blank=True, db_default="", default="", max_length=50)),+ ("cancelled_at", models.DateTimeField(blank=True, null=True)),+ (+ "activated_by",+ models.ForeignKey(+ db_constraint=False,+ null=True,+ on_delete=django.db.models.deletion.SET_NULL,+ related_name="+",+ to=settings.AUTH_USER_MODEL,+ ),+ ),+ (+ "report",+ models.ForeignKey(+ blank=True,+ null=True,+ on_delete=django.db.models.deletion.SET_NULL,+ to="signals.signalreport",+ ),+ ),+ (+ "team",+ models.OneToOneField(+ db_constraint=False,+ on_delete=django.db.models.deletion.CASCADE,+ related_name="+",+ to="posthog.team",+ ),+ ),+ ],+ options={+ "indexes": [+ models.Index(+ condition=models.Q(+ ("cancelled_at__isnull", True),+ ("queued_at__isnull", True),+ ("send_started_at__isnull", True),+ ),+ fields=["id"],+ name="signals_first_report_pending",+ )+ ],+ },+ ),+ ]diff --git a/products/signals/backend/migrations/max_migration.txt b/products/signals/backend/migrations/max_migration.txtindex e8b3c3234040..c18661923fb2 100644--- a/products/signals/backend/migrations/max_migration.txt+++ b/products/signals/backend/migrations/max_migration.txt@@ -1 +1 @@-0188_useractivitysummary_skipped_status+0189_first_report_notificationdiff --git a/products/signals/backend/models.py b/products/signals/backend/models.pyindex f61ec849e281..9ec3bbaf32d2 100644--- a/products/signals/backend/models.py+++ b/products/signals/backend/models.py@@ -187,6 +187,34 @@ class AutonomyPriority(models.TextChoices):GITHUB_LABEL_NAME_MAX_LENGTH = 50+class SignalFirstReportNotification(UUIDModel):+ # Activation and report visibility belong to the environment, so the recipient must not be canonicalized to its parent.+ objects = EnvironmentScopedManager()++ team = models.OneToOneField("posthog.Team", on_delete=models.CASCADE, related_name="+", db_constraint=False)+ activated_by = models.ForeignKey(+ "posthog.User", on_delete=models.SET_NULL, null=True, related_name="+", db_constraint=False+ )+ activated_at = models.DateTimeField(auto_now_add=True)+ report = models.ForeignKey("signals.SignalReport", on_delete=models.SET_NULL, null=True, blank=True)+ message_data = models.JSONField(default=dict, db_default={})+ send_started_at = models.DateTimeField(null=True, blank=True)+ next_attempt_at = models.DateTimeField(null=True, blank=True)+ queued_at = models.DateTimeField(null=True, blank=True)+ message_id = models.CharField(max_length=200, null=True, blank=True)+ last_error = models.CharField(max_length=50, default="", db_default="", blank=True)+ cancelled_at = models.DateTimeField(null=True, blank=True)++ class Meta:+ indexes = [+ models.Index(+ fields=["id"],+ condition=models.Q(queued_at__isnull=True, cancelled_at__isnull=True, send_started_at__isnull=True),+ name="signals_first_report_pending",+ )+ ]++class SignalTeamConfig(ModelActivityMixin, UUIDModel):team = models.OneToOneField("posthog.Team",diff --git a/products/signals/backend/receivers.py b/products/signals/backend/receivers.pyindex eb4032b5e373..feaa67c4553f 100644--- a/products/signals/backend/receivers.py+++ b/products/signals/backend/receivers.py@@ -24,7 +24,7 @@ from posthog.event_usage import groupsfrom posthog.models.user import Userfrom products.signals.backend.artefact_attribution import ArtefactAttribution-from products.signals.backend.models import SignalReport, SignalReportArtefact+from products.signals.backend.models import SignalFirstReportNotification, SignalReport, SignalReportArtefactfrom products.signals.backend.report_embeddings import (emit_report_embeddings,emit_report_tombstone,@@ -38,6 +38,39 @@ if TYPE_CHECKING:logger = structlog.get_logger(__name__)++def _enqueue_first_report_notification(team_id: int) -> None:+ if (+ SignalFirstReportNotification.objects.for_team(team_id)+ .filter(queued_at__isnull=True, cancelled_at__isnull=True, send_started_at__isnull=True)+ .exists()+ ):+ from products.signals.backend.first_report_notification_tasks import (+ dispatch_first_report_notification, # noqa: PLC0415 - keep the task graph off Django startup+ )++ dispatch_first_report_notification.delay(team_id)+++def _schedule_first_report_notification(team_id: int) -> None:+ def enqueue() -> None:+ _enqueue_first_report_notification(team_id)++ transaction.on_commit(enqueue, robust=True)+++@receiver(post_save, sender=SignalReport)+def enqueue_first_report_notification(+ sender: type[SignalReport],+ instance: SignalReport,+ created: bool,+ update_fields: set[str] | None = None,+ **kwargs: Any,+) -> None:+ if instance.status == SignalReport.Status.READY and (created or update_fields is None or "status" in update_fields):+ _schedule_first_report_notification(instance.team_id)++_SNOOZE_SOURCE_STATUSES = frozenset({SignalReport.Status.READY, SignalReport.Status.RESOLVED, SignalReport.Status.MONITORING})@@ -819,6 +852,8 @@ def sync_report_latest_actionability_on_save(tools. Not gated on `created`, because `update_content` edits a judgment row in place."""_sync_report_latest_actionability(instance)+ if instance.type == SignalReportArtefact.ArtefactType.ACTIONABILITY_JUDGMENT:+ _schedule_first_report_notification(instance.team_id)def _deleted_directly(origin: Any) -> bool:diff --git a/products/signals/backend/report_content_gates.py b/products/signals/backend/report_content_gates.pyindex 4fcb32b12eff..ace9ee7e1d4d 100644--- a/products/signals/backend/report_content_gates.py+++ b/products/signals/backend/report_content_gates.py@@ -21,6 +21,7 @@ logger = structlog.get_logger(__name__)REPORT_METRICS_FLAG = "signals-report-metrics"REPORT_MONITORING_FLAG = "signals-report-monitoring"+FIRST_REPORT_EMAIL_FLAG = "signals-first-report-email"RESEARCH_REVIEWER_SELECTION_FLAG = "signals-research-reviewer-selection"@@ -78,6 +79,10 @@ def team_report_metrics_enabled(team_id: int) -> bool:return _team_flag_enabled(REPORT_METRICS_FLAG, team_id)+def team_first_report_email_enabled(team_id: int) -> bool:+ return _team_flag_enabled(FIRST_REPORT_EMAIL_FLAG, team_id, enable_in_debug=False)++def organization_report_monitoring_enabled(organization_id: UUID) -> bool:return _organization_flag_enabled(REPORT_MONITORING_FLAG, organization_id, enable_in_debug=False, only_evaluate_locally=Truediff --git a/products/signals/backend/tasks.py b/products/signals/backend/tasks.pyindex 5ff77a8d88fb..39dc9d8c26ee 100644--- a/products/signals/backend/tasks.py+++ b/products/signals/backend/tasks.py@@ -28,6 +28,10 @@ from posthog.scoping_audit import skip_team_scope_auditfrom posthog.temporal.common.utils import is_stale_connection_read_only_errorfrom products.signals.backend.billing import current_billing_period_bounds+from products.signals.backend.first_report_notification_tasks import (+ dispatch_first_report_notification as dispatch_first_report_notification,+ sweep_first_report_notifications as sweep_first_report_notifications,+)from products.signals.backend.implementation_dispatch_tasks import (dispatch_implementation_replacement as dispatch_implementation_replacement,sweep_implementation_dispatches as sweep_implementation_dispatches,diff --git a/products/signals/backend/test/test_first_report_notification.py b/products/signals/backend/test/test_first_report_notification.pynew file mode 100644index 000000000000..eb92d710ea2d--- /dev/null+++ b/products/signals/backend/test/test_first_report_notification.py@@ -0,0 +1,431 @@+from datetime import UTC, datetime, timedelta+from uuid import uuid4++import time_machine+from posthog.test.base import BaseTest+from unittest.mock import Mock, patch++from django.core.exceptions import ImproperlyConfigured+from django.db import transaction+from django.test import override_settings+from django.utils import timezone++from celery.exceptions import Retry+from parameterized import parameterized++from posthog.constants import AvailableFeature+from posthog.models import Organization, Team, User+from posthog.transactional_email import (+ TransactionalEmailDeliveryUncertain,+ TransactionalEmailRejected,+ TransactionalEmailRetryableError,+ send_transactional_email,+)++from products.access_control.backend.models.access_control import AccessControl+from products.signals.backend.first_report_notification import (+ deliver_first_report_email,+ register_first_report_notification,+)+from products.signals.backend.first_report_notification_tasks import (+ dispatch_first_report_notification,+ sweep_first_report_notifications,+)+from products.signals.backend.models import SignalFirstReportNotification, SignalReport, SignalReportArtefact+from products.signals.backend.report_access import may_read_reports++MODULE = "products.signals.backend.first_report_notification"+TASK_MODULE = "products.signals.backend.first_report_notification_tasks"+++@time_machine.travel("2026-01-15T12:00:00Z", tick=False)+@override_settings(SITE_URL="https://app.example.com")+class TestFirstReportNotification(BaseTest):+ def setUp(self) -> None:+ super().setUp()+ self.template_id = uuid4()+ self.enterContext(+ override_settings(+ POSTHOG_HOST="https://us.posthog.com",+ POSTHOG_PROJECT_ID=123456789,+ POSTHOG_TRANSACTIONAL_EMAIL_API_KEY="phs_fake_transactional_key",+ )+ )+ self.enterContext(patch(f"{MODULE}.SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID", str(self.template_id)))+ self.enterContext(patch(f"{MODULE}.is_cloud", return_value=True))+ self.enterContext(patch(f"{TASK_MODULE}.is_cloud", return_value=True))+ self.email_flag = self.enterContext(patch(f"{MODULE}.team_first_report_email_enabled", return_value=True))+ response = Mock(status_code=202)+ response.json.return_value = {"message_id": "example-message-id"}+ self.post = self.enterContext(patch("posthog.transactional_email.requests.post", return_value=response))+ self.send = self.enterContext(patch(f"{MODULE}.send_transactional_email", wraps=send_transactional_email))+ register_first_report_notification(team=self.team, user=self.user)++ def report(self, **overrides: object) -> SignalReport:+ return SignalReport.objects.create(+ **{+ "team": self.team,+ "status": SignalReport.Status.READY,+ "title": "Checkout errors increased",+ "summary": "An actionable report.",+ "signal_count": 1,+ "total_weight": 1,+ "first_visible_at": timezone.now(),+ "latest_actionability": "immediately_actionable",+ "latest_already_addressed": False,+ **overrides,+ }+ )++ def notification(self) -> SignalFirstReportNotification:+ return SignalFirstReportNotification.objects.for_team(self.team.id).get()++ @time_machine.travel("2026-01-15T12:01:00Z", tick=False)+ def test_first_report_targets_activator_once_per_project(self) -> None:+ first = self.report(first_visible_at=timezone.now() - timedelta(seconds=1))+ self.report()+ other_user = User.objects.create_and_join(self.organization, "[email protected]", None)+ register_first_report_notification(team=self.team, user=other_user)++ deliver_first_report_email(self.team.id)+ deliver_first_report_email(self.team.id)++ self.send.assert_called_once_with(+ str(self.template_id),+ to=self.user.email,+ distinct_id=str(self.user.distinct_id),+ message_data={+ "project_id": self.team.id,+ "report_id": str(first.id),+ "report_title": first.title,+ "report_url": f"https://app.example.com/project/{self.team.id}/inbox/reports/{first.id}",+ "activation_id": str(self.notification().id),+ },+ )+ assert self.notification().queued_at is not None+ assert self.notification().message_id == "example-message-id"+ assert self.post.call_args.args[0] == (+ f"https://us.posthog.com/api/projects/123456789/messaging_templates/{self.template_id}/send/"+ )+ other_team = Team.objects.create(organization=self.organization, name="Another project")+ register_first_report_notification(team=other_team, user=self.user)+ self.report(team=other_team)+ deliver_first_report_email(other_team.id)+ assert self.send.call_count == 2++ @parameterized.expand(+ [+ ("researching", {"status": SignalReport.Status.IN_PROGRESS}),+ ("suppressed", {"status": SignalReport.Status.SUPPRESSED}),+ ("failed", {"status": SignalReport.Status.FAILED}),+ ("needs_input", {"status": SignalReport.Status.PENDING_INPUT}),+ ("not_actionable", {"latest_actionability": "not_actionable"}),+ ("already_addressed", {"latest_already_addressed": True}),+ ("not_judged", {"latest_actionability": None}),+ ("empty", {"summary": ""}),+ ("never_visible", {"first_visible_at": None}),+ ("before_activation", {"first_visible_at": datetime(2026, 1, 14, tzinfo=UTC)}),+ ]+ )+ def test_waits_for_an_eligible_report(self, _name: str, overrides: dict[str, object]) -> None:+ self.report(**overrides)+ deliver_first_report_email(self.team.id)+ self.send.assert_not_called()+ assert self.notification().send_started_at is None+ assert self.notification().cancelled_at is None++ @parameterized.expand([("inactive",), ("removed",), ("no_email",), ("no_access",), ("deleted",)])+ def test_does_not_substitute_another_recipient(self, reason: str) -> None:+ self.report()+ if reason == "inactive":+ self.user.is_active = False+ self.user.save(update_fields=["is_active"])+ elif reason == "removed":+ self.organization.members.remove(self.user)+ elif reason == "no_email":+ self.user.email = ""+ self.user.save(update_fields=["email"])+ elif reason == "deleted":+ SignalFirstReportNotification.objects.for_team(self.team.id).update(activated_by=None)+ with patch(f"{MODULE}.may_read_reports", return_value=reason != "no_access"):+ deliver_first_report_email(self.team.id)+ self.send.assert_not_called()+ assert self.notification().cancelled_at is not None++ @parameterized.expand(+ [+ ("quota", TransactionalEmailRetryableError("rate_limited")),+ ("connect", TransactionalEmailRetryableError("connect_timeout")),+ ("template", TransactionalEmailRejected("http_404")),+ ("setup", ImproperlyConfigured()),+ ]+ )+ @time_machine.travel("2026-01-15T12:01:00Z", tick=False)+ def test_confirmed_rejection_retries_the_same_report(self, _name: str, error: Exception) -> None:+ first = self.report()+ self.send.side_effect = error+ with self.assertRaises(type(error)):+ deliver_first_report_email(self.team.id)+ initial_send = self.send.call_args+ assert self.notification().send_started_at is None+ assert self.notification().last_error+ self.report(first_visible_at=timezone.now() - timedelta(seconds=1))+ self.send.side_effect = None++ deliver_first_report_email(self.team.id)++ assert self.send.call_args == initial_send+ assert initial_send.kwargs["message_data"]["report_id"] == str(first.id)+ assert self.notification().queued_at is not None++ def test_project_access_is_required_even_with_task_access(self) -> None:+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},+ {"key": AvailableFeature.ROLE_BASED_ACCESS, "name": AvailableFeature.ROLE_BASED_ACCESS},+ ]+ self.organization.save(update_fields=["available_product_features"])+ recipient = User.objects.create_and_join(self.organization, "[email protected]", None)+ SignalFirstReportNotification.objects.for_team(self.team.id).update(activated_by=recipient)+ AccessControl.objects.create(+ team=self.team, resource="project", resource_id=str(self.team.id), access_level="none"+ )+ self.report()+ assert may_read_reports(user=recipient, team=self.team)++ deliver_first_report_email(self.team.id)++ self.send.assert_not_called()+ assert self.notification().cancelled_at is not None++ def test_retry_after_blocks_early_dispatch_and_recovery_until_due(self) -> None:+ first = self.report()+ self.post.return_value.status_code = 429+ self.post.return_value.headers = {"Retry-After": "3600"}+ self.post.return_value.json.return_value = {"code": "rate_limited"}++ with patch(f"{TASK_MODULE}.capture_exception"), self.assertRaises(Retry) as raised:+ dispatch_first_report_notification.apply(args=(self.team.id,), throw=True)++ assert raised.exception.when == 3600+ assert self.notification().next_attempt_at == timezone.now() + timedelta(hours=1)+ assert self.notification().send_started_at is None+ initial_send = self.send.call_args+ self.post.return_value.status_code = 202+ self.post.return_value.json.return_value = {"message_id": "example-message-id"}++ with time_machine.travel("2026-01-15T12:59:59Z", tick=False):+ self.report()+ dispatch_first_report_notification(self.team.id)+ with patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue:+ sweep_first_report_notifications()+ enqueue.assert_not_called()+ self.send.assert_called_once()++ with time_machine.travel("2026-01-15T13:00:00Z", tick=False):+ with patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue:+ sweep_first_report_notifications()+ enqueue.assert_called_once_with(self.team.id)+ dispatch_first_report_notification(self.team.id)++ assert self.send.call_count == 2+ assert self.send.call_args == initial_send+ assert initial_send.kwargs["message_data"]["report_id"] == str(first.id)+ assert self.notification().queued_at is not None+ assert self.notification().next_attempt_at is None++ @parameterized.expand(+ [(SignalReport.Status.CANDIDATE,), (SignalReport.Status.IN_PROGRESS,), (SignalReport.Status.PENDING_INPUT,)]+ )+ def test_selected_report_waits_for_research_before_retry(self, status: str) -> None:+ report = self.report()+ self.send.side_effect = TransactionalEmailRetryableError("rate_limited")+ with self.assertRaises(TransactionalEmailRetryableError):+ deliver_first_report_email(self.team.id)+ initial_send = self.send.call_args+ self.send.side_effect = None+ SignalReport.objects.filter(pk=report.pk).update(status=status)++ deliver_first_report_email(self.team.id)++ self.send.assert_called_once()+ assert self.notification().cancelled_at is None+ assert self.notification().send_started_at is None+ SignalReport.objects.filter(pk=report.pk).update(status=SignalReport.Status.READY)+ deliver_first_report_email(self.team.id)+ assert self.send.call_count == 2+ assert self.send.call_args == initial_send+ assert self.notification().queued_at is not None++ @parameterized.expand(+ [+ ("ambiguous_response", TransactionalEmailDeliveryUncertain("request_failed")),+ ("invalid_response", ValueError()),+ ]+ )+ def test_uncertain_send_is_not_repeated(self, _name: str, error: Exception) -> None:+ self.report()+ self.send.side_effect = error+ with self.assertRaises(type(error)):+ deliver_first_report_email(self.team.id)+ self.send.side_effect = None+ deliver_first_report_email(self.team.id)+ with patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue:+ sweep_first_report_notifications()+ enqueue.assert_not_called()+ self.send.assert_called_once()+ assert self.notification().send_started_at is not None+ assert self.notification().queued_at is None+ assert self.notification().last_error == "delivery_uncertain"++ def test_worker_loss_does_not_expire_a_send_and_duplicate_it(self) -> None:+ self.report()+ SignalFirstReportNotification.objects.for_team(self.team.id).update(+ send_started_at=timezone.now() - timedelta(days=1)+ )+ deliver_first_report_email(self.team.id)+ self.send.assert_not_called()++ def test_concurrent_dispatch_does_not_send_twice(self) -> None:+ self.report()++ def send(*_args: object, **_kwargs: object) -> str:+ deliver_first_report_email(self.team.id)+ return "example-message-id"++ self.send.side_effect = send+ deliver_first_report_email(self.team.id)+ self.send.assert_called_once()+ assert self.notification().queued_at is not None++ def test_environment_activation_and_reports_keep_their_own_recipient(self) -> None:+ child = Team.objects.create(organization=self.organization, parent_team=self.team, name="Staging")+ other_user = User.objects.create_and_join(self.organization, "[email protected]", None)+ register_first_report_notification(team=child, user=other_user)+ report = self.report(team=child)+ deliver_first_report_email(self.team.id)+ self.send.assert_not_called()+ deliver_first_report_email(child.id)+ sent = self.send.call_args.kwargs+ assert sent["to"] == other_user.email+ assert sent["distinct_id"] == str(other_user.distinct_id)+ assert sent["message_data"]["project_id"] == child.id+ assert sent["message_data"]["report_id"] == str(report.id)+ assert self.notification().queued_at is None++ @parameterized.expand([("suppressed",), ("deleted",)])+ def test_selected_report_removed_before_retry_is_not_replaced(self, reason: str) -> None:+ report = self.report()+ self.send.side_effect = TransactionalEmailRetryableError("rate_limited")+ with self.assertRaises(TransactionalEmailRetryableError):+ deliver_first_report_email(self.team.id)+ if reason == "deleted":+ report.delete()+ else:+ SignalReport.objects.filter(pk=report.pk).update(status=SignalReport.Status.SUPPRESSED)+ self.report()+ self.send.side_effect = None+ deliver_first_report_email(self.team.id)+ self.send.assert_called_once()+ assert self.notification().cancelled_at is not None++ def test_disabled_flag_preserves_notification_until_enabled(self) -> None:+ self.report()+ self.email_flag.return_value = False++ deliver_first_report_email(self.team.id)++ self.send.assert_not_called()+ assert self.notification().send_started_at is None+ assert self.notification().cancelled_at is None+ assert self.notification().report_id is None+ self.email_flag.return_value = True+ deliver_first_report_email(self.team.id)+ self.send.assert_called_once()+ assert self.notification().queued_at is not None++ @parameterized.expand([("not_cloud",), ("no_project",), ("no_key",), ("no_host",)])+ def test_disabled_delivery_does_not_claim_a_notification(self, reason: str) -> None:+ self.report()+ with (+ patch(f"{MODULE}.is_cloud", return_value=reason != "not_cloud"),+ patch(f"{TASK_MODULE}.is_cloud", return_value=reason != "not_cloud"),+ patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue,+ override_settings(+ POSTHOG_PROJECT_ID=0 if reason == "no_project" else 123456789,+ POSTHOG_TRANSACTIONAL_EMAIL_API_KEY="" if reason == "no_key" else "phs_fake_transactional_key",+ POSTHOG_HOST="" if reason == "no_host" else "https://us.posthog.com",+ ),+ ):+ deliver_first_report_email(self.team.id)+ with self.assertNumQueries(0):+ sweep_first_report_notifications()+ enqueue.assert_not_called()+ self.send.assert_not_called()+ assert self.notification().send_started_at is None++ def test_rollback_does_not_queue_a_notification_and_transient_ready_is_not_sent(self) -> None:+ with patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue:+ with self.captureOnCommitCallbacks(execute=True):+ with self.assertRaises(RuntimeError), transaction.atomic():+ self.report()+ raise RuntimeError("rollback")+ enqueue.assert_not_called()+ with self.captureOnCommitCallbacks(execute=True), transaction.atomic():+ report = self.report()+ report.status = SignalReport.Status.CANDIDATE+ report.save(update_fields=["status"])+ enqueue.assert_called_once_with(self.team.id)+ deliver_first_report_email(self.team.id)+ self.send.assert_not_called()++ def test_sweep_recovers_a_missing_enqueue_without_crossing_tenants(self) -> None:+ self.report()+ other_team = Team.objects.create(organization=Organization.objects.create(name="Other org"))+ self.report(team=other_team)+ with patch(f"{TASK_MODULE}.dispatch_first_report_notification.delay") as enqueue:+ sweep_first_report_notifications()+ enqueue.assert_called_once_with(self.team.id)+ deliver_first_report_email(other_team.id)+ self.send.assert_not_called()+ deliver_first_report_email(self.team.id)+ self.send.assert_called_once()++ @parameterized.expand([("report",), ("judgment",)])+ def test_enqueue_failure_does_not_abort_later_commit_callbacks(self, trigger: str) -> None:+ report = self.report(status=SignalReport.Status.IN_PROGRESS)+ following_callback = Mock()+ with (+ patch(+ f"{TASK_MODULE}.dispatch_first_report_notification.delay",+ side_effect=RuntimeError("broker unavailable"),+ ),+ self.assertLogs(level="ERROR"),+ self.captureOnCommitCallbacks(execute=True),+ ):+ if trigger == "report":+ report.status = SignalReport.Status.READY+ report.save(update_fields=["status"])+ else:+ SignalReportArtefact.objects.create(+ team=self.team,+ report=report,+ type=SignalReportArtefact.ArtefactType.ACTIONABILITY_JUDGMENT,+ content='{"actionability":"immediately_actionable","already_addressed":false}',+ )+ transaction.on_commit(following_callback)+ following_callback.assert_called_once()++ @parameterized.expand([("dispatch",), ("sweep",)])+ def test_task_captures_and_reraises_failures(self, task_name: str) -> None:+ error = RuntimeError("notification failed")+ target = "deliver_first_report_email" if task_name == "dispatch" else "dispatch_first_report_notification.delay"+ task = dispatch_first_report_notification if task_name == "dispatch" else sweep_first_report_notifications+ args = (self.team.id,) if task_name == "dispatch" else ()+ with (+ patch(f"{TASK_MODULE}.{target}", side_effect=error),+ patch(f"{TASK_MODULE}.capture_exception") as capture,+ self.assertRaises(RuntimeError) as raised,+ ):+ task(*args)+ assert raised.exception is error+ capture.assert_called_once_with(error)diff --git a/products/signals/backend/test/test_inbox_onboarding.py b/products/signals/backend/test/test_inbox_onboarding.pyindex 017a61d70ae7..762b914f91b9 100644--- a/products/signals/backend/test/test_inbox_onboarding.py+++ b/products/signals/backend/test/test_inbox_onboarding.py@@ -24,6 +24,7 @@ from posthog.models.utils import generate_random_token_personal, hash_key_valuefrom posthog.oauth_provenance import SANDBOX_OAUTH_APP_CLIENT_IDSfrom products.signals.backend.models import (+ SignalFirstReportNotification,SignalScoutConfig,SignalScoutSuggestionSet,SignalSourceConfig,@@ -242,6 +243,9 @@ class TestInboxOnboarding(APIBaseTest):assert config.autostart_enabled is automatic_implementationassert config.default_autostart_priority == "P1"assert config.onboarding["activated_by"] == self.user.id+ notification = SignalFirstReportNotification.objects.for_team(self.team.id).get()+ assert notification.activated_by_id == self.user.id+ assert notification.queued_at is Noneassert capture.call_args.kwargs["properties"]["variant"] == variantassert capture.call_args.kwargs["properties"] == {"$set_once": {"email": self.user.email},diff --git a/products/signals/backend/test/test_report_content_gates.py b/products/signals/backend/test/test_report_content_gates.pyindex 709d93881328..da4e2b6e84ba 100644--- a/products/signals/backend/test/test_report_content_gates.py+++ b/products/signals/backend/test/test_report_content_gates.py@@ -1,3 +1,4 @@+from collections.abc import Callablefrom uuid import UUIDfrom unittest.mock import patch@@ -10,6 +11,7 @@ from parameterized import parameterizedfrom products.signals.backend.report_content_gates import (organization_report_metrics_enabled,organization_report_monitoring_enabled,+ team_first_report_email_enabled,team_report_metrics_enabled,team_report_monitoring_enabled,)@@ -20,9 +22,19 @@ _FLAG_EVALUATION = "products.signals.backend.report_content_gates.feature_enableclass TestReportContentGates(SimpleTestCase):@parameterized.expand(- [(f"{debug}_{enabled}", debug, enabled) for debug in [False, True] for enabled in [False, True]]+ [+ (f"{name}_{debug}_{enabled}", gate, flag, local, debug, enabled)+ for name, gate, flag, local in [+ ("monitoring", team_report_monitoring_enabled, "signals-report-monitoring", True),+ ("first_report_email", team_first_report_email_enabled, "signals-first-report-email", False),+ ]+ for debug in [False, True]+ for enabled in [False, True]+ ])- def test_monitoring_requires_the_organization_flag(self, _name: str, debug: bool, enabled: bool) -> None:+ def test_lifecycle_feature_requires_the_organization_flag(+ self, _name: str, gate: Callable[[int], bool], flag: str, local: bool, debug: bool, enabled: bool+ ) -> None:organization_id = UUID("00000000-0000-0000-0000-000000000001")with (override_settings(DEBUG=debug),@@ -31,16 +43,16 @@ class TestReportContentGates(SimpleTestCase):):team_lookup.return_value.get.return_value = organization_id- assert team_report_monitoring_enabled(7) is enabled+ assert gate(7) is enabledteam_lookup.return_value.get.assert_called_once_with(id=7)evaluate.assert_called_once_with(- "signals-report-monitoring",+ flag,str(organization_id),groups={"organization": str(organization_id)},group_properties={"organization": {"id": str(organization_id)}},send_feature_flag_events=False,- only_evaluate_locally=True,+ only_evaluate_locally=local,)@override_settings(DEBUG=False)@@ -60,20 +72,30 @@ class TestReportContentGates(SimpleTestCase):assert organization_report_metrics_enabled(organization_id)remote_flags.assert_called_once()+ @parameterized.expand(+ [("monitoring", team_report_monitoring_enabled), ("first_report_email", team_first_report_email_enabled)]+ )@override_settings(DEBUG=True)- def test_monitoring_fails_closed_when_flag_evaluation_fails(self) -> None:+ def test_lifecycle_feature_fails_closed_when_flag_evaluation_fails(+ self, _name: str, gate: Callable[[int], bool]+ ) -> None:with patch(_TEAM_LOOKUP) as team_lookup, patch(_FLAG_EVALUATION, side_effect=RuntimeError("unavailable")):team_lookup.return_value.get.return_value = UUID("00000000-0000-0000-0000-000000000001")- assert not team_report_monitoring_enabled(7)+ assert not gate(7)+ @parameterized.expand(+ [("monitoring", team_report_monitoring_enabled), ("first_report_email", team_first_report_email_enabled)]+ )@override_settings(DEBUG=True)- def test_monitoring_fails_closed_when_the_team_cannot_be_read(self) -> None:+ def test_lifecycle_feature_fails_closed_when_the_team_cannot_be_read(+ self, _name: str, gate: Callable[[int], bool]+ ) -> None:with (patch(_TEAM_LOOKUP, side_effect=RuntimeError("unavailable")),patch(_FLAG_EVALUATION) as evaluate,):- assert not team_report_monitoring_enabled(7)+ assert not gate(7)evaluate.assert_not_called()