trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/notifications/models.py

@@ -0,0 +1,1148 @@
+"""Notifications data model (ADR-0075).
+
+Three entities power the unified @mention surface that #311 ships first and
+#476 (deferred Notes) will inherit unchanged:
+
+- Mention — polymorphic append-only @mention record. Source is one of a small
+  set of nullable FKs (today: TaskComment; #476 adds TaskNote). Target is
+  either a user (direct mention) or a group key (snapshot expanded to per-
+  user Notification rows at write time).
+- Notification — per-recipient inbox row. Single feed surface so a future
+  #476 note-mention lands in the same UI as today's comment-mention.
+- NotificationPreference — per-user `(event_type, channel)` toggle. ADR-0049's
+  NOTIFICATION_CHANNELS registry is *registered but not yet consumed*: channel
+  validation runs off the ProjectNotificationChannel TextChoices (see
+  serializers._VALID_CHANNELS), so an Enterprise-registered slack_dm/teams_dm/sms
+  would currently be rejected. Wiring the registry is #3252.
+- ProjectNotificationPreference — per-(project, user) routing matrix plus
+  daily quiet-hours window. Backs the Project > Notifications settings page
+  (#522); orthogonal to NotificationPreference, which is the *global* mention
+  feed default.
+"""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+# Lazy FK target — Django resolves the string, so no migration is produced.
+_PROJECT_MODEL = "projects.Project"
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class MentionScope(models.TextChoices):
+    """Visibility scope of a @mention's source content.
+
+    `PROJECT_VISIBLE` is the only value used by #311 (comments); #476 will
+    populate `TEAM_ONLY` for team-private Decisions and the visibility gate
+    on the Decisions view. The scope field exists on day one so #476's gate
+    isn't bolted on as an afterthought.
+    """
+
+    PROJECT_VISIBLE = "project_visible", "Project visible"
+    TEAM_ONLY = "team_only", "Team only"
+    PRIVATE = "private", "Private"
+
+
+class NotificationEventType(models.TextChoices):
+    """Event types that produce notifications.
+
+    Mapped to NotificationPreference rows so users can independently toggle
+    in_app / email per event type. The own-task events (#639, ADR-0085) reuse
+    the WebhookEventType string values where one exists (task.assigned,
+    task.due_date_changed) so event names share one source of truth across the
+    webhook and notification subsystems; comment_on_my_task is notification-only.
+    @mentions of me are covered by MENTION_INDIVIDUAL / MENTION_GROUP and the
+    existing mention path — task.mentioned is not duplicated here.
+    """
+
+    MENTION_INDIVIDUAL = "mention_individual", "Direct @mention"
+    MENTION_GROUP = "mention_group", "Group @mention"
+    # Own-task events (#639) — a user's reach over work assigned to or owned by them.
+    TASK_ASSIGNED = "task.assigned", "Assigned to me"
+    TASK_DUE_DATE_CHANGED = "task.due_date_changed", "Due date changed on my task"
+    COMMENT_ON_MY_TASK = "comment_on_my_task", "Comment on my task"
+    # Contributor signal (#855, #476) — fires when a task I own is flagged blocked
+    # by someone else. One of the two events in the SIGNAL_ONLY_EVENTS preset.
+    TASK_BLOCKED = "task.blocked", "A task I own is blocked"
+    # Sprint-close bridge digest (#861) — the PM cohort is told when a closed
+    # sprint's reforecast materially shifts a bound milestone's finish. Email
+    # defaults ON for this one event (see DEFAULT_PREFERENCES): the issue's whole
+    # point is reaching the PM *outside* her session, which in-app alone can't do.
+    MILESTONE_FORECAST_SHIFTED = "milestone.forecast_shifted", "Milestone forecast shifted"
+    # Schedule-canvas reschedule of a sprint-mate's task (#497) — the rest of the
+    # ACTIVE sprint team learns a committed date moved. In-app only for v1.
+    SPRINT_TASK_RESCHEDULED = "sprint.task_rescheduled", "Task in my sprint rescheduled"
+    # Signal-privacy ceiling-raise ratification (#1275, ADR-0104 Amendment B) — a
+    # team-owned vote to widen a signal's visibility. "Opened" reaches eligible
+    # voters so the 72h window is discoverable off the Settings page; "resolved"
+    # reaches voters + the proposer with the outcome. In-app ON, email opt-in OFF
+    # (Priya's hard-NO was on un-opted email, not on an in-app inbox row).
+    SIGNAL_CEILING_PROPOSAL_OPENED = (
+        "signal.ceiling_proposal_opened",
+        "Team signal visibility proposal opened",
+    )
+    SIGNAL_CEILING_PROPOSAL_RESOLVED = (
+        "signal.ceiling_proposal_resolved",
+        "Team signal visibility proposal resolved",
+    )
+    # Project-delete team notification (#1115, VoC Option C). A project soft-delete
+    # is a large destructive write that removes the whole team's workspace; every
+    # member (bar the deleter) is told in-app who deleted it, so a project does not
+    # simply vanish from under them. In-app ON by default; email strictly opt-in OFF
+    # (Priya's hard-NO on un-opted email); NEVER push — the durable inbox row is the
+    # only channel, so the notification can never arrive as an unsolicited interrupt.
+    PROJECT_DELETED = "project.deleted", "A project I belong to was deleted"
+    # Stale-task daily nudge (ADR-0200). A daily scan fans this out to the assignee
+    # of a non-terminal task that has sat in its current status past the project's
+    # configurable threshold (default 7 days) — the "task I forgot in Review" slip.
+    # Distinct from the synchronous is_stalled board-card chip (ADR-0115, 3-day dwell):
+    # this is opt-in, configurable, and reaches the owner asynchronously. In-app ON,
+    # email opt-in OFF (Priya's un-opted-email hard-NO).
+    TASK_STALE = "task.stale", "A task I own has gone stale"
+    # Sprint-close carryover reassignment (ADR-0232, #1470). Fires to the assignee
+    # when close-time carry-over moves a task they own to the next sprint or the
+    # backlog — the "my work hopped sprints over the weekend and nobody told me"
+    # gap (Priya's load-bearing 🔴 in the 2026-07-01 agile VoC audit). A durable
+    # in-app inbox row, NOT a push: ADR-0102 §6 withholds push for board mechanics,
+    # but carryover is an actual reassignment of committed work (closer to
+    # task.assigned), so the inbox row reaches the assignee off-session without
+    # interrupting. In-app ON, email opt-in OFF (Priya's un-opted-email hard-NO).
+    TASK_MOVED_SPRINT = "task.moved_sprint", "A task I own was carried to another sprint"
+    # Sprint-membership scope change (ADR-0412, #1946). Fires to the project lead
+    # cohort (role >= ADMIN) when a task actually ENTERS or LEAVES an ACTIVE sprint
+    # — the "PM/admin silently added a task to the active sprint" audit gap Jordan
+    # (PO) and Alex (SM) raised as hard-NOs in the 2026-07-14 activity-streams VoC
+    # audit. Distinct from TASK_MOVED_SPRINT above (that reaches the *assignee* on
+    # close-time carryover); this reaches the *accountable leads* on a live-scope
+    # change. In-app ON, email opt-in OFF (Priya's un-opted-email hard-NO), and
+    # deliberately NOT in DND_BYPASS_EVENTS — a scope change is not a hard interrupt.
+    SPRINT_MEMBERSHIP_CHANGED = (
+        "sprint.membership_changed",
+        "A task entered or left an active sprint",
+    )
+    # Project-finish shift (#1911, third #82 schedule-notification rule — companion
+    # to #1668's dependency-slip / became-critical pair). Fires when a
+    # ProjectForecastSnapshot's cpm_finish moves by more than the project's
+    # configurable Project.end_date_shift_threshold_days versus the immediately
+    # prior snapshot. Reaches the PM/Owner cohort (role >= ADMIN), same targeting
+    # as MILESTONE_FORECAST_SHIFTED (#861) — see notify_project_end_date_shift.
+    PROJECT_END_DATE_SHIFTED = "project.end_date_shifted", "Project end date shifted"
+    # Amend on a committed plan (#2964). Fires when a structural edit lands on a
+    # project that has been committed (lifecycle=active, ADR-0845 baseline taken).
+    # Reaches the people whose work is affected — NEVER a block: the design is
+    # explicit that Amend records and tells, it does not gate. In-app ON so the
+    # change is visible where decisions get argued about; email opt-in OFF, the
+    # same un-opted-email floor every contributor signal keeps.
+    PLAN_AMENDED = "plan.amended", "A committed plan I work on was changed"
+    # Project configuration change that moves the surface everyone works on
+    # (#2972, epic #2743). Removing a board lane, hiding a board column, hiding a
+    # leaf surface, or switching the methodology preset re-arranges where every
+    # assignee's work appears — and before this, only the person who clicked knew.
+    #
+    # Two properties this event exists to hold, both easy to erode later:
+    #   1. It fires ONLY on a change that moves or hides work. A rename, a color,
+    #      a WIP limit, an added lane — nothing. "A setting was saved" is exactly
+    #      the notification the issue exists to refuse, so the trigger is the
+    #      consequence, not the write.
+    #   2. Its body names what the change did to THIS recipient's own items
+    #      (rendered per recipient via create_event_notifications_batch), which is
+    #      why the notice is worth an inbox row at all.
+    # Reaches everyone with work in the project rather than the whole membership:
+    # the claim it makes is about the recipient's own items, and a member with no
+    # items has nothing to be told about. In-app ON, email opt-in OFF (Priya's
+    # un-opted-email hard-NO). Deliberately NOT in DND_BYPASS_EVENTS — a
+    # re-arranged board needs to be seen, not to interrupt.
+    PROJECT_CONFIG_CHANGED = (
+        "project.config_changed",
+        "The board or views I work on were reconfigured",
+    )
+    # Scheduled digests (ADR-0663, #2407) — the first CLOCK-driven events in this
+    # enum. Every other member fires from a domain event; these two fire from Beat
+    # on the recipient's own weekly slot (UserNotificationSettings.digest_*), which
+    # is why they are the only pair defaulting OFF on BOTH channels: a weekly send
+    # nobody asked for is exactly the volume the matrix exists to prevent. Content
+    # is read from already-computed facts (compute_program_rollup / _load_band) —
+    # a digest never derives a number the UI does not already show.
+    PROGRAM_HEALTH_DIGEST = "program.health_digest", "Weekly program health digest"
+    RESOURCE_OVERALLOCATION_DIGEST = (
+        "resource.overallocation_digest",
+        "Weekly resource overallocation digest",
+    )
+    # Membership grant / role-change (#3645). ProjectMembershipViewSet and
+    # ProgramMembershipViewSet could create, change and revoke access with no
+    # signal reaching the affected person — their only tell was a project or
+    # program appearing in their list. These two fire to the added or
+    # role-changed user only (not on revoke, which is audit-only — see the
+    # issue). In-app ON, email opt-in OFF, matching every other contributor
+    # signal in this table (Priya's un-opted-email hard-NO).
+    MEMBERSHIP_GRANTED = "membership.granted", "Added to a project or program"
+    MEMBERSHIP_ROLE_CHANGED = "membership.role_changed", "Role changed on a project or program"
+
+
+class NotificationChannel(models.TextChoices):
+    """Delivery channels (OSS keys only).
+
+    ADR-0049's NOTIFICATION_CHANNELS registry is *intended* to open this axis to
+    Enterprise channels (slack_dm / teams_dm / sms), but nothing reads it yet, so
+    registering one does not make it accepted. Wiring it is #3252.
+    """
+
+    IN_APP = "in_app", "In-app"
+    EMAIL = "email", "Email"
+
+
+# ---------------------------------------------------------------------------
+# Manager — scope-respecting queryset (ADR-0075 must-fix)
+# ---------------------------------------------------------------------------
+
+
+class MentionManager(models.Manager["Mention"]):
+    """Default manager for ``Mention``.
+
+    Mention visibility is enforced through ``NotificationViewSet``'s
+    ``recipient=request.user`` filter; there is no direct Mention list endpoint.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Mention
+# ---------------------------------------------------------------------------
+
+
+class Mention(models.Model):
+    """Append-only @mention record. Polymorphic source via nullable FKs.
+
+    Exactly one source FK and at least one target (user OR group_key) must be
+    set — enforced by CheckConstraints. The `mentioned_group_key` is preserved
+    on the row for display ("@scrum-team was mentioned"), independently of
+    the per-recipient Notification rows that fan out from group resolution.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    mentioner = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        related_name="mentions_authored",
+    )
+
+    # Target — direct user OR group_key (or both, if the group resolution
+    # happens to include the mentioned user explicitly).
+    mentioned_user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="mentions_received",
+    )
+    # Empty string = no group key (Django convention DJ001: no nullable CharField).
+    mentioned_group_key = models.CharField(max_length=32, blank=True, default="")
+
+    # Polymorphic source. 0.2 has TaskComment only; #476 will add task_note.
+    # CheckConstraint requires exactly one (today: task_comment must be set).
+    task_comment = models.ForeignKey(
+        "projects.TaskComment",
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="mentions",
+    )
+
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        related_name="mentions",
+    )
+    scope = models.CharField(
+        max_length=32,
+        choices=MentionScope.choices,
+        default=MentionScope.PROJECT_VISIBLE,
+    )
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+
+    objects = MentionManager()
+
+    class Meta:
+        db_table = "notifications_mention"
+        ordering = ["-created_at"]
+        constraints = [
+            models.CheckConstraint(
+                condition=(
+                    models.Q(mentioned_user__isnull=False) | ~models.Q(mentioned_group_key="")
+                ),
+                name="mention_must_have_target",
+            ),
+            # In 0.2 only task_comment is a valid source; when #476 ships,
+            # widen this to allow task_note as well.
+            models.CheckConstraint(
+                condition=models.Q(task_comment__isnull=False),
+                name="mention_must_have_source",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["mentioned_user", "-created_at"], name="ix_mention_user_recent"),
+            models.Index(fields=["project", "-created_at"], name="ix_mention_project_recent"),
+        ]
+
+    def __str__(self) -> str:
+        target = self.mentioned_user_id or f"@{self.mentioned_group_key}"
+        return f"Mention(to={target}, scope={self.scope})"
+
+
+# ---------------------------------------------------------------------------
+# Notification — per-recipient inbox row
+# ---------------------------------------------------------------------------
+
+
+class Notification(models.Model):
+    """Per-recipient unread notification. Generated from Mention fan-out (0.2)
+    and future event types. Single inbox surface — every #476 mention lands
+    here unchanged.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    recipient = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="notifications",
+    )
+
+    # Source — a notification is EITHER mention-sourced (mention set, rendered
+    # from the comment) OR event-sourced (#639, ADR-0085 §3: event_type + the
+    # pre-rendered subject/body set, mention null). Both feed the one inbox.
+    mention = models.ForeignKey(
+        Mention,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="notifications",
+    )
+    # Event-sourced notifications (own-task events) — blank for mention rows.
+    event_type = models.CharField(max_length=64, blank=True, default="")
+    subject = models.CharField(max_length=255, blank=True, default="")
+    body = models.TextField(blank=True, default="")
+
+    # Optional deep-link target (#497/#861). Mention rows resolve their task via
+    # the comment; event rows have no such path, so this FK lets the inbox row
+    # link straight to the affected task/milestone in the schedule. SET_NULL +
+    # related_name="+" — a deleted task should never cascade-delete the historical
+    # notification, and no reverse accessor on Task is needed.
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="+",
+    )
+
+    # Nullable since ADR-0663: a scheduled digest spans the recipient's whole
+    # membership set and has no single owning project, so forcing one would mean
+    # picking an arbitrary project and mis-scoping the row. Every event- and
+    # mention-sourced row still sets it; only the account-scoped digests are NULL.
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="notifications",
+    )
+
+    is_read = models.BooleanField(default=False, db_index=True)
+    is_archived = models.BooleanField(default=False)
+    # Per-notification snooze (ADR-0216 §1). A row with snoozed_until > now() is
+    # hidden from the All/Unread inbox views (and the unread-count query) until
+    # the timestamp passes, then reappears — a pure query-time filter, no Celery.
+    # Null = not snoozed. Indexed because every non-snoozed list query filters on it.
+    snoozed_until = models.DateTimeField(null=True, blank=True, db_index=True)
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+    read_at = models.DateTimeField(null=True, blank=True)
+
+    # Email delivery state (drained via drain_notification_emails Beat task).
+    email_pending = models.BooleanField(default=False, db_index=True)
+    email_sent_at = models.DateTimeField(null=True, blank=True)
+    email_failed_at = models.DateTimeField(null=True, blank=True)
+    email_attempts = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        db_table = "notifications_notification"
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["recipient", "is_read", "-created_at"], name="ix_notif_unread"),
+            models.Index(
+                fields=["email_pending", "-created_at"],
+                name="ix_notif_email_pending",
+                condition=models.Q(email_pending=True),
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"Notification(to={self.recipient_id}, mention={self.mention_id})"
+
+
+# ---------------------------------------------------------------------------
+# NotificationPreference — per-user (event_type, channel) toggle
+# ---------------------------------------------------------------------------
+
+
+class NotificationPreference(models.Model):
+    """Per-user channel preference, per event type.
+
+    Defaults backfill on first GET (see services.get_or_create_defaults). The
+    channel column is a plain CharField, so the *schema* imposes no channel list —
+    but serializer validation does (_VALID_CHANNELS, built from the
+    ProjectNotificationChannel TextChoices), so an ADR-0049 Enterprise channel
+    (slack_dm, teams_dm, sms) does not yet round-trip. Wiring is #3252.
+    """
+
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="notification_preferences",
+    )
+    event_type = models.CharField(max_length=64)  # NotificationEventType + future
+    channel = models.CharField(max_length=32)  # NotificationChannel + Enterprise extensions
+    enabled = models.BooleanField()
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "notifications_preference"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "event_type", "channel"],
+                name="uq_notifpref_user_event_channel",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        state = "on" if self.enabled else "off"
+        return f"NotificationPreference({self.event_type}/{self.channel}={state})"
+
+
+# ---------------------------------------------------------------------------
+# Defaults (ADR-0075 V2 VoC — Priya's "flip email default OFF")
+# ---------------------------------------------------------------------------
+
+
+DEFAULT_PREFERENCES: list[tuple[str, str, bool]] = [
+    (NotificationEventType.MENTION_INDIVIDUAL, NotificationChannel.IN_APP, True),
+    (NotificationEventType.MENTION_INDIVIDUAL, NotificationChannel.EMAIL, False),
+    (NotificationEventType.MENTION_GROUP, NotificationChannel.IN_APP, True),
+    (NotificationEventType.MENTION_GROUP, NotificationChannel.EMAIL, False),
+    # Own-task events (#639): in-app ON, email OFF. Email is strictly opt-in —
+    # aggressive email defaults were Priya's VoC blocker (ADR-0085 §1, ADR-0075 V2).
+    (NotificationEventType.TASK_ASSIGNED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.TASK_ASSIGNED, NotificationChannel.EMAIL, False),
+    (NotificationEventType.TASK_DUE_DATE_CHANGED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.TASK_DUE_DATE_CHANGED, NotificationChannel.EMAIL, False),
+    (NotificationEventType.COMMENT_ON_MY_TASK, NotificationChannel.IN_APP, True),
+    (NotificationEventType.COMMENT_ON_MY_TASK, NotificationChannel.EMAIL, False),
+    # Blocked signal (#855): in-app ON, email OFF — same opt-in-email rule. This
+    # event is one of the two kept ON by the Signal-only preset below.
+    (NotificationEventType.TASK_BLOCKED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.TASK_BLOCKED, NotificationChannel.EMAIL, False),
+    # #861 — the bridge digest is the deliberate exception to the email-OFF
+    # default: a PM who is not logged in when the team closes a sprint at 7pm
+    # must still be pushed the milestone-confidence shift, or "automatic" still
+    # demands she remember to log in (the issue's core blocker). Still fully
+    # matrix-overridable — a PM can mute either channel.
+    (NotificationEventType.MILESTONE_FORECAST_SHIFTED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.MILESTONE_FORECAST_SHIFTED, NotificationChannel.EMAIL, True),
+    # #497 — in-app only for v1 (email digest/push explicitly out of scope).
+    (NotificationEventType.SPRINT_TASK_RESCHEDULED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.SPRINT_TASK_RESCHEDULED, NotificationChannel.EMAIL, False),
+    # #1275 / ADR-0104 Amendment B — ceiling-raise proposal discovery. In-app ON so
+    # voters see the ask without navigating to Settings; email strictly opt-in OFF
+    # (Priya's hard-NO is preserved — un-opted email noise, not the in-app inbox).
+    (NotificationEventType.SIGNAL_CEILING_PROPOSAL_OPENED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.SIGNAL_CEILING_PROPOSAL_OPENED, NotificationChannel.EMAIL, False),
+    (NotificationEventType.SIGNAL_CEILING_PROPOSAL_RESOLVED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.SIGNAL_CEILING_PROPOSAL_RESOLVED, NotificationChannel.EMAIL, False),
+    # #1115 — project-delete team notification. In-app ON so every member learns
+    # their project was deleted; email opt-in OFF (Priya's un-opted-email hard-NO).
+    (NotificationEventType.PROJECT_DELETED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.PROJECT_DELETED, NotificationChannel.EMAIL, False),
+    # ADR-0200 — stale-task daily nudge. In-app ON so the owner sees the reminder in
+    # their inbox; email opt-in OFF (Priya's un-opted-email hard-NO). A daily digest
+    # of forgotten cards must not become un-asked-for email.
+    (NotificationEventType.TASK_STALE, NotificationChannel.IN_APP, True),
+    (NotificationEventType.TASK_STALE, NotificationChannel.EMAIL, False),
+    # ADR-0232 (#1470) — sprint-close carryover reassignment. In-app ON so the
+    # assignee learns their committed work moved across the close→plan seam; email
+    # opt-in OFF (Priya's un-opted-email hard-NO).
+    (NotificationEventType.TASK_MOVED_SPRINT, NotificationChannel.IN_APP, True),
+    (NotificationEventType.TASK_MOVED_SPRINT, NotificationChannel.EMAIL, False),
+    # ADR-0412 (#1946) — sprint-membership scope change. In-app ON so the project
+    # leads see a mid-sprint injection/removal in their inbox; email opt-in OFF
+    # (Priya's un-opted-email hard-NO), matching every other contributor signal.
+    (NotificationEventType.SPRINT_MEMBERSHIP_CHANGED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.SPRINT_MEMBERSHIP_CHANGED, NotificationChannel.EMAIL, False),
+    # #2964 — an amend to committed work. In-app ON so the people whose plan
+    # changed see it; email opt-in OFF, matching every other contributor signal.
+    (NotificationEventType.PLAN_AMENDED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.PLAN_AMENDED, NotificationChannel.EMAIL, False),
+    # #1911 — project end-date shift. In-app ON so the PM/Owner cohort sees the
+    # slip in their inbox; email opt-in OFF (Priya's un-opted-email hard-NO),
+    # matching every other schedule-drift signal in this table.
+    (NotificationEventType.PROJECT_END_DATE_SHIFTED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.PROJECT_END_DATE_SHIFTED, NotificationChannel.EMAIL, False),
+    # #2972 — a board lane removed, a column or view hidden, or the methodology
+    # preset switched. In-app ON so the people whose work moved learn it moved
+    # without waiting to notice; email opt-in OFF, the same un-opted-email floor
+    # every contributor signal in this table keeps.
+    (NotificationEventType.PROJECT_CONFIG_CHANGED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.PROJECT_CONFIG_CHANGED, NotificationChannel.EMAIL, False),
+    # ADR-0663 (#2407) — the scheduled digests are the ONLY rows in this table that
+    # default OFF on both channels, and deliberately so. Every entry above fires
+    # from something the user did or something that happened to their work, so an
+    # in-app row is welcome by default; a weekly clock-driven send is traffic the
+    # user has to actually want. Defaulting in_app OFF also makes the feature inert
+    # on upgrade: create_event_notifications skips a recipient whose in_app is off,
+    # so no digest row exists for anyone until they opt in. Flipping either of these
+    # to True is a product decision with a volume cost (ADR-0663 §Risks), not a
+    # tidy-up.
+    (NotificationEventType.PROGRAM_HEALTH_DIGEST, NotificationChannel.IN_APP, False),
+    (NotificationEventType.PROGRAM_HEALTH_DIGEST, NotificationChannel.EMAIL, False),
+    (NotificationEventType.RESOURCE_OVERALLOCATION_DIGEST, NotificationChannel.IN_APP, False),
+    (NotificationEventType.RESOURCE_OVERALLOCATION_DIGEST, NotificationChannel.EMAIL, False),
+    # #3645 — membership grant / role-change. In-app ON so the affected person
+    # sees who changed their access and to what; email opt-in OFF, the same
+    # un-opted-email floor every contributor signal in this table keeps.
+    (NotificationEventType.MEMBERSHIP_GRANTED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.MEMBERSHIP_GRANTED, NotificationChannel.EMAIL, False),
+    (NotificationEventType.MEMBERSHIP_ROLE_CHANGED, NotificationChannel.IN_APP, True),
+    (NotificationEventType.MEMBERSHIP_ROLE_CHANGED, NotificationChannel.EMAIL, False),
+]
+
+
+# ---------------------------------------------------------------------------
+# Signal-only preset (#855) — the contributor-friendly minimal profile
+# ---------------------------------------------------------------------------
+# Priya (Team Member) gave a hard-NO on noisy notifications. "Signal-only" is the
+# one-click profile that keeps ON only the two events that mean "something needs
+# my attention" — a task of mine got blocked, or a deadline moved — and turns
+# everything else OFF. It is applied by POST /me/notification-preferences/
+# apply-preset/ (a wholesale write of the per-(event,channel) rows), NOT a new
+# stored model: the matrix stays the single source of truth so the existing
+# data-driven settings page (ADR-0085) keeps rendering whatever rows the server
+# returns. The "everything" preset restores DEFAULT_PREFERENCES.
+SIGNAL_ONLY_EVENTS: frozenset[str] = frozenset(
+    {
+        NotificationEventType.TASK_BLOCKED,
+        NotificationEventType.TASK_DUE_DATE_CHANGED,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Do-Not-Disturb bypass set (#1707, ADR-0292)
+# ---------------------------------------------------------------------------
+# The account-wide DND switch (UserNotificationSettings.dnd_enabled) silences
+# transient channels (email/push) for routine events. These four events ALWAYS
+# deliver on every channel regardless of DND — the "needs my attention now"
+# signals a muted bell must never swallow: a task of mine got blocked, a team
+# signal-visibility vote opened or resolved, or a milestone forecast shifted.
+#
+# This is deliberately NOT SIGNAL_ONLY_EVENTS: that set is the contributor
+# settings *preset* (task.blocked + task.due_date_changed) and is the wrong
+# membership for a safety bypass — it would let a routine due-date change punch
+# through DND while silencing a signal-ceiling proposal. The two sets are
+# distinct on purpose; keep this membership in step as new critical event types
+# are added (it is the load-bearing safety contract, #1707).
+DND_BYPASS_EVENTS: frozenset[str] = frozenset(
+    {
+        NotificationEventType.TASK_BLOCKED,
+        NotificationEventType.SIGNAL_CEILING_PROPOSAL_OPENED,
+        NotificationEventType.SIGNAL_CEILING_PROPOSAL_RESOLVED,
+        NotificationEventType.MILESTONE_FORECAST_SHIFTED,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Project-scoped notification preferences (#522)
+# ---------------------------------------------------------------------------
+
+
+class ProjectNotificationEventType(models.TextChoices):
+    """Project-scoped notification events surfaced on Project > Notifications.
+
+    Disjoint from `NotificationEventType` (which today only covers @mention
+    fan-out for the inbox surface). The project page covers the broader set
+    of routing decisions a PM makes per-project — task assignment, slips,
+    risk creation, sprint lifecycle, etc.
+    """
+
+    TASK_ASSIGNED = "task_assigned", "Task assigned to me"
+    TASK_OVERDUE = "task_overdue", "Task I own is overdue"
+    COMMENT_MENTION = "comment_mention", "Mention (@) in a comment"
+    STATUS_CHANGE = "status_change", "Task moves to another column"
+    BUDGET_ALERT = "budget_alert", "Budget threshold crossed"
+    RISK_CREATED = "risk_created", "Risk created or escalated"
+    MILESTONE_REACHED = "milestone_reached", "Milestone reached"
+    SPRINT_START = "sprint_start", "Sprint started"
+    SPRINT_END = "sprint_end", "Sprint closed"
+
+
+#: Project-scoped events that a delivery path actually consults (#2904).
+#: ``COMMENT_MENTION`` is the only one: ``notifications/services.py`` gates the
+#: mention fan-out on it. Everything else in the enum is declared below.
+PROJECT_NOTIFICATION_DISPATCHED_EVENTS: frozenset[str] = frozenset(
+    {ProjectNotificationEventType.COMMENT_MENTION.value}
+)
+
+#: Members that exist in the matrix but that **nothing dispatches** — the settings
+#: page renders them, and toggling one has no effect in either direction
+#: (TODO(#3016) wire the dispatchers).
+#:
+#: They are kept rather than deleted because they are a stated product intent, and
+#: the API reports them in ``event_delivery`` as ``false`` so a client can say so
+#: instead of implying a delivery that never happens. Crucially they default **OFF** on
+#: every channel: eight events defaulting ON across in-app, email and Slack told an
+#: admin that eight kinds of notification were being delivered, which made turning
+#: one *off* the only action with any apparent meaning — and it had none either.
+#:
+#: This set and :data:`PROJECT_NOTIFICATION_DISPATCHED_EVENTS` must together cover
+#: the enum exactly; ``test_project_notification_dispatch_coverage`` enforces it, so
+#: a member cannot be added without someone deciding which side it is on.
+PROJECT_NOTIFICATION_UNDISPATCHED_EVENTS: frozenset[str] = frozenset(
+    {
+        ProjectNotificationEventType.TASK_ASSIGNED.value,
+        ProjectNotificationEventType.TASK_OVERDUE.value,
+        ProjectNotificationEventType.STATUS_CHANGE.value,
+        ProjectNotificationEventType.BUDGET_ALERT.value,
+        ProjectNotificationEventType.RISK_CREATED.value,
+        ProjectNotificationEventType.MILESTONE_REACHED.value,
+        ProjectNotificationEventType.SPRINT_START.value,
+        ProjectNotificationEventType.SPRINT_END.value,
+    }
+)
+
+
+class ProjectNotificationChannel(models.TextChoices):
+    """Columns of the project notification matrix — not a claim that each delivers.
+
+    Which of these TruePPM actually delivers on is not restated here: it is
+    :data:`PROJECT_NOTIFICATION_DELIVERABLE_CHANNELS` and its complement
+    :data:`PROJECT_NOTIFICATION_UNDELIVERABLE_CHANNELS` below, the one place that
+    classification is made and the pair a coverage test holds against this enum.
+    ``slack`` and ``mobile_push`` are on the undeliverable side: nothing sends to
+    them and **no setting anywhere turns them on** — there is no integration to
+    configure, which is what the pre-#3378 wording here claimed. They remain as
+    columns so a member can record routing intent that applies once delivery ships.
+
+    This axis is *not* the ADR-0049 ``NOTIFICATION_CHANNELS`` registry — that is the
+    account-wide ``NotificationPreference.channel`` vocabulary, registered but not
+    yet consumed here (see the module docstring); whether the two converge is #3252.
+
+    A toggle in the matrix is therefore user intent, and the API says which columns
+    that intent can reach today via ``channel_delivery`` (#3378).
+    """
+
+    IN_APP = "in_app", "In-app"
+    EMAIL = "email", "Email"
+    SLACK = "slack", "Slack"
+    MOBILE_PUSH = "mobile_push", "Mobile push"
+
+
+#: Matrix columns TruePPM has a delivery path for (#3378).
+#:
+#: A literal, deliberately. The obvious move — deriving it from ADR-0049's
+#: ``NOTIFICATION_CHANNELS`` registrations — is wrong twice over. The registry is
+#: the vocabulary of the *account-wide* ``NotificationPreference.channel`` surface,
+#: not of this matrix, and it is registered but not yet consumed (see the module
+#: docstring); whether the two axes converge is #3252's open question, so pinning
+#: this to it would encode a decision nobody has made. And the registry is
+#: populated at ``AppConfig.ready()``, so a value read from it would make the
+#: published OpenAPI schema depend on which apps happened to be loaded when it was
+#: generated — including Enterprise's, which would change the *OSS* schema.
+#:
+#: What keeps the literal honest is
+#: ``tests/apps/notifications/test_project_notification_channel_coverage.py``: the
+#: two sets must cover :class:`ProjectNotificationChannel` exactly and be disjoint,
+#: and an AST walk asserts a channel declared undeliverable is named by no dispatch
+#: site.
+PROJECT_NOTIFICATION_DELIVERABLE_CHANNELS: frozenset[str] = frozenset(
+    {
+        ProjectNotificationChannel.IN_APP.value,
+        ProjectNotificationChannel.EMAIL.value,
+    }
+)
+
+#: Columns the matrix renders that **nothing delivers on** (TODO(#3252)).
+#:
+#: Not "the integration is not configured" — there is nothing to configure. No code
+#: in ``apps/notifications`` sends to either, and no setting anywhere turns them on.
+#: They are kept as columns because they are a stated product intent and a member's
+#: stored routing choice survives until delivery ships; the API reports them in
+#: ``channel_delivery`` as ``false`` so a client can label the column instead of
+#: rendering a control that cannot do anything.
+PROJECT_NOTIFICATION_UNDELIVERABLE_CHANNELS: frozenset[str] = frozenset(
+    {
+        ProjectNotificationChannel.SLACK.value,
+        ProjectNotificationChannel.MOBILE_PUSH.value,
+    }
+)
+
+
+# Default matrix — applied lazily on first GET (no per-user backfill on join).
+# A cell defaults ON only where both halves of the claim hold: the event has a
+# dispatcher (PROJECT_NOTIFICATION_DISPATCHED_EVENTS) and the channel has a
+# delivery path (PROJECT_NOTIFICATION_DELIVERABLE_CHANNELS). Everything else
+# defaults OFF, because a default of True is a claim that something will be
+# delivered.
+_T = ProjectNotificationEventType
+_C = ProjectNotificationChannel
+
+
+def _all_off() -> dict[str, bool]:
+    """Every channel off — the default for an event nothing dispatches (#2904)."""
+    return {_C.IN_APP: False, _C.EMAIL: False, _C.SLACK: False, _C.MOBILE_PUSH: False}
+
+
+PROJECT_NOTIFICATION_DEFAULT_MATRIX: dict[str, dict[str, bool]] = {
+    # Only COMMENT_MENTION has a dispatch path, so it is the only row that may
+    # default ON — a default of True is a claim that something will be delivered.
+    # Slack and mobile push stay OFF even here: the event IS dispatched, but those
+    # two columns are in PROJECT_NOTIFICATION_UNDELIVERABLE_CHANNELS, so ON would be
+    # the same false claim one axis over. Flip them ON in the same change that ships
+    # their delivery (TODO(#3252)).
+    #
+    # This changes what a NEW row is seeded with, and nothing else. The JSONField
+    # default is materialized in full at row creation and every read path prefers the
+    # stored value, so a member who has already opened this page keeps whatever they
+    # have — deliberately. Force-clearing a stored cell would destroy a routing
+    # intent the whole surface exists to preserve, and it is no longer misleading
+    # either way: `channel_delivery` now labels the column on every response.
+    _T.COMMENT_MENTION: {
+        _C.IN_APP: True,
+        _C.EMAIL: True,
+        _C.SLACK: False,
+        _C.MOBILE_PUSH: False,
+    },
+    # TODO(#3016): every row below is dispatched by nothing. They default OFF on
+    # every channel so the settings matrix does not promise a delivery that never
+    # comes; the API reports them in event_delivery as false so a client can label
+    # them. Flip a row back to True in the same change that wires its dispatcher.
+    _T.TASK_ASSIGNED: _all_off(),
+    _T.TASK_OVERDUE: _all_off(),
+    _T.STATUS_CHANGE: _all_off(),
+    _T.BUDGET_ALERT: _all_off(),
+    _T.RISK_CREATED: _all_off(),
+    _T.MILESTONE_REACHED: _all_off(),
+    _T.SPRINT_START: _all_off(),
+    _T.SPRINT_END: _all_off(),
+}
+
+
+def _default_matrix() -> dict[str, dict[str, bool]]:
+    """Deep-copy of the default matrix used as the JSONField default.
+
+    Django requires a callable; returning the literal would share mutable
+    state across rows.
+    """
+    return {evt: dict(chans) for evt, chans in PROJECT_NOTIFICATION_DEFAULT_MATRIX.items()}
+
+
+#: Every event type the ``event_delivery`` map reports on, as plain strings.
+#:
+#: The literal key set of :data:`PROJECT_NOTIFICATION_DEFAULT_MATRIX`, which is what
+#: :func:`project_notification_event_delivery` iterates. Named here so the published
+#: OpenAPI schema for ``event_delivery`` can enumerate the same keys from the same
+#: source rather than restating them — a new event type then reaches the declared
+#: contract in the edit that adds it, instead of leaving the schema quietly short a
+#: property (#3396, #3399).
+PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS: tuple[str, ...] = tuple(
+    sorted(str(event) for event in PROJECT_NOTIFICATION_DEFAULT_MATRIX)
+)
+
+
+def project_notification_event_delivery() -> dict[str, bool]:
+    """``{event_type: is a dispatcher wired}`` for every matrix row (#2904).
+
+    Derived from :data:`PROJECT_NOTIFICATION_DISPATCHED_EVENTS` rather than restating
+    the classification, so the coverage test that pins that set also pins this map.
+
+    Lives beside the two constants rather than in the view that returns it because
+    the serializer that *declares* the response shape needs the same key set, and a
+    second copy in the schema layer is exactly the drift #3399 asked to close.
+    """
+    return {
+        event: event in PROJECT_NOTIFICATION_DISPATCHED_EVENTS
+        for event in PROJECT_NOTIFICATION_DELIVERY_REPORTED_EVENTS
+    }
+
+
+#: Every channel the ``channel_delivery`` map reports on, as plain strings (#3378).
+#:
+#: The matrix's own column vocabulary — :class:`ProjectNotificationChannel` — which
+#: is a different, closed set from the ADR-0049 registry keys: Enterprise registers
+#: ``slack_dm`` / ``teams_dm`` / ``sms`` there and none of them is a column here.
+#: Named so the published OpenAPI schema enumerates the same keys from the same
+#: source rather than restating them.
+PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS: tuple[str, ...] = tuple(
+    sorted(str(channel.value) for channel in ProjectNotificationChannel)
+)
+
+
+def project_notification_channel_delivery() -> dict[str, bool]:
+    """``{channel: does TruePPM deliver on it}`` for every matrix column (#3378).
+
+    The per-column counterpart to :func:`project_notification_event_delivery`, and
+    the reason it exists is the same: the web client was hard-coding
+    ``['slack', 'mobile_push']`` and its own comment said the copy should not
+    survive. Whether a channel delivers is server state — it changes in the release a
+    delivery path lands — so a client-side copy drifts the moment one does.
+
+    Derived from :data:`PROJECT_NOTIFICATION_DELIVERABLE_CHANNELS` rather than
+    restating the classification, so the coverage test that pins that set also pins
+    this map. The two maps are deliberately independent axes: a cell is live only
+    when its event is dispatched **and** its channel delivers, which is why a
+    per-row badge could never have covered this — ``comment_mention`` *is*
+    dispatched and its Slack cell still delivers nothing.
+
+    Server-global: the answer does not vary by user or by project. It rides on the
+    per-user preference document only so a client can label the grid in one render.
+    """
+    return {
+        channel: channel in PROJECT_NOTIFICATION_DELIVERABLE_CHANNELS
+        for channel in PROJECT_NOTIFICATION_DELIVERY_REPORTED_CHANNELS
+    }
+
+
+class ProjectNotificationPreference(models.Model):
+    """Per-(project, user) notification routing matrix and quiet-hours window.
+
+    One row per user per project. The matrix is a `{event_type: {channel: bool}}`
+    JSON document — the row count stays small (one per user per project) and
+    PATCH is a single UPDATE rather than a 36-row diff. Missing event/channel
+    keys fall back to the default matrix on read, so a stale row won't break
+    when the event set grows.
+
+    schema_version tracks the shape of ``matrix`` (ADR-0086 / ADR-0204, #1916 —
+    this surface was named by #522 but missed the #645 registry sweep). On read,
+    ``ProjectNotificationPreferenceSerializer`` runs the payload through the
+    forward-migration registry (``schema_migrations.migrate_payload``) keyed on
+    this column, mirroring ``BoardSavedView.schema_version``. Rows created before
+    this field existed are backfilled to ``schema_version=1`` by the migration
+    default; every event type in ``PROJECT_NOTIFICATION_DEFAULT_MATRIX`` shipped
+    together at #522, so no existing row is actually missing a key and the v0
+    path is a no-op for them today — it exists so a *future* event-type addition
+    (or an externally-imported row that skipped ``validate`` at write time) has a
+    forward-migration path instead of relying solely on the view-layer
+    ``_merge_matrix`` overlay.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        related_name="notification_preferences_by_user",
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="project_notification_preferences",
+    )
+    matrix = models.JSONField(default=_default_matrix)
+    schema_version = models.IntegerField(
+        default=1,
+        help_text="Matrix shape version; upgraded on read via the migration registry (ADR-0086).",
+    )
+
+    # Per-user-per-project kill-switch (#589). When True, all notification
+    # dispatch for this user on this project is suppressed regardless of the
+    # matrix — an opt-out path for members who haven't dialed in their
+    # routing yet. The matrix remains preserved so unpausing restores prior
+    # preferences exactly.
+    paused = models.BooleanField(default=False)
+
+    quiet_hours_enabled = models.BooleanField(default=True)
+    quiet_hours_from = models.TimeField(default=datetime.time(20, 0))
+    quiet_hours_until = models.TimeField(default=datetime.time(7, 0))
+
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "notifications_project_preference"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["project", "user"],
+                name="uq_projnotifpref_project_user",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["project", "user"], name="ix_projnotifpref_proj_user"),
+        ]
+
+    def __str__(self) -> str:
+        return f"ProjectNotificationPreference(project={self.project_id}, user={self.user_id})"
+
+
+class UserNotificationSettings(models.Model):
+    """Per-user, account-wide notification settings — the Do-Not-Disturb switch
+    (#1707, ADR-0292).
+
+    One row per user, lazily created on first access
+    (:func:`services.get_or_create_notification_settings`) — no backfill on user
+    create, mirroring :func:`services.get_or_create_default_preferences`; the
+    absence of a row reads as DND off. Distinct in grain from the per-(event,
+    channel) :class:`NotificationPreference` matrix and the per-project
+    :class:`ProjectNotificationPreference`: this is a single account-wide switch
+    that silences transient channels (email/push) across every project, exactly
+    as quiet hours gate only transient channels — the durable in-app inbox row is
+    never silenced and :data:`DND_BYPASS_EVENTS` always deliver.
+
+    A plain ``Model`` (no ``server_version``): a personal installation preference,
+    never synced or broadcast, mirroring ``ProjectNotificationPreference`` and
+    ``profiles.UserProfile``. Shaped to grow a scheduled quiet-hours window + a
+    per-user timezone later; only the DND switch ships now (ADR-0292 §4).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="notification_settings",
+    )
+    # Account-wide Do-Not-Disturb. When True, transient channels (email/push) are
+    # suppressed for all non-bypass events; the durable in-app inbox row is
+    # unaffected and DND_BYPASS_EVENTS always deliver on every channel.
+    dnd_enabled = models.BooleanField(default=False)
+    # Weekly digest slot (ADR-0663, #2407) — the "per-user timezone + scheduled
+    # window" this model was documented from the start as being shaped to grow
+    # (ADR-0292 §4). ONE slot covers both digest event types: a schedule per event
+    # would double the settings surface to serve a case nobody asked for.
+    #
+    # The slot is only ever *read* by the Beat sweep; it is inert for a user who
+    # has not enabled a digest preference, so the defaults below are a starting
+    # point for the picker rather than an implied subscription.
+    digest_weekday = models.IntegerField(
+        default=6,
+        choices=[
+            (0, "Monday"),
+            (1, "Tuesday"),
+            (2, "Wednesday"),
+            (3, "Thursday"),
+            (4, "Friday"),
+            (5, "Saturday"),
+            (6, "Sunday"),
+        ],
+        help_text="Day of week for scheduled digests, 0=Monday..6=Sunday (Python weekday()).",
+    )
+    digest_hour = models.IntegerField(
+        default=17,
+        help_text="Local hour (0-23) at which scheduled digests are sent.",
+    )
+    # Blank = fall back to settings.TIME_ZONE. Empty string is the single unset
+    # state (project DJ001 convention — no nullable CharFields).
+    digest_timezone = models.CharField(
+        max_length=64,
+        blank=True,
+        default="",
+        help_text="IANA timezone for the digest slot; blank uses the server timezone.",
+    )
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "notifications_user_settings"
+        verbose_name = "user notification settings"
+        verbose_name_plural = "user notification settings"
+
+    def __str__(self) -> str:
+        state = "on" if self.dnd_enabled else "off"
+        return f"UserNotificationSettings(user={self.user_id}, dnd={state})"
+
+
+class NotificationDigestRun(models.Model):
+    """Idempotency ledger for scheduled digests (ADR-0663, #2407).
+
+    One row per ``(user, event_type, period_start)``. The Beat sweep
+    ``get_or_create``s the row **before** building content and skips when
+    ``created`` is False, so a double-fire, a manual re-queue, or an overlapping
+    sweep cannot mail a second copy of the same week's digest. The unique
+    constraint is what makes that check atomic across concurrent workers — the
+    Redis lock on the task is belt-and-braces, not the primary guard.
+
+    Creating the row *before* the content build means a mid-build crash leaves a
+    "sent" marker for a digest that never arrived. That is deliberate and fails
+    closed: a missing weekly digest is recoverable by logging in, whereas a
+    duplicate erodes trust in a channel whose entire value is that it is quiet.
+
+    A plain ``Model`` (no ``server_version``): an operational record, never synced
+    to mobile and never broadcast, mirroring :class:`UserNotificationSettings`.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name="digest_runs",
+    )
+    event_type = models.CharField(max_length=64)
+    # User-local week-start date of the send. Date (not datetime) so the ledger
+    # grain matches the weekly cadence and a DST-shifted resend collides.
+    period_start = models.DateField()
+    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
+    # How many inbox rows the send produced. 0 is a legitimate value — an honest
+    # "nothing at risk this week" digest is still a send (ADR-0663 §4).
+    notification_count = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        db_table = "notifications_digest_run"
+        constraints = [
+            models.UniqueConstraint(
+                fields=["user", "event_type", "period_start"],
+                name="uniq_digest_run_user_event_period",
+            ),
+        ]
+        indexes = [
+            # Nightly purge scans by age alone.
+            models.Index(fields=["created_at"], name="digestrun_created_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"NotificationDigestRun(user={self.user_id}, {self.event_type}, {self.period_start})"
+
+
+# ---------------------------------------------------------------------------
+# Workspace SMTP configuration (#712, ADR-0213)
+# ---------------------------------------------------------------------------
+
+
+class EmailTransportMode(models.TextChoices):
+    """Outbound-mail transport for the workspace.
+
+    ``CLOUD`` is the unconfigured default — the send path falls back to the
+    process-global Django ``EMAIL_BACKEND`` (Helm env), so a fresh install
+    behaves exactly as it did before #712. The other three build an SMTP
+    connection from this row; ``SENDGRID`` / ``SES`` are SMTP relays with a
+    provider-fixed host so 0.4 needs no new backend class (ADR-0213 §2).
+    """
+
+    CLOUD = "cloud", "TruePPM cloud (Django settings)"
+    SMTP = "smtp", "Custom SMTP"
+    SENDGRID = "sendgrid", "SendGrid"
+    SES = "ses", "Amazon SES"
+
+
+class EmailSecurity(models.TextChoices):
+    """SMTP connection security."""
+
+    NONE = "none", "None"
+    TLS = "tls", "STARTTLS"
+    SSL = "ssl", "SSL/TLS"
+
+
+class WorkspaceEmailSettings(models.Model):
+    """Singleton writable SMTP configuration for the workspace (#712, ADR-0213).
+
+    Installation config, not a synced/board-scoped resource, so there is no
+    ``server_version``. Single-row is enforced by the unique ``singleton_key``
+    (the ``workspace.Workspace`` / ADR-0081 precedent) and the row is lazily
+    created on first access via :meth:`load` — no seed migration.
+
+    The SMTP password is encrypted at rest with Fernet (``password_ciphertext``)
+    reusing ``apps.integrations.encryption`` and is **never** returned by the
+    API — the serializer exposes only :attr:`password_is_set`. Decryption
+    happens server-side only, at send time, in ``resolve_email_connection``.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    # Always 1 — the unique constraint makes a second row impossible.
+    singleton_key = models.PositiveSmallIntegerField(default=1, editable=False, unique=True)
+
+    transport_mode = models.CharField(
+        max_length=16,
+        choices=EmailTransportMode.choices,
+        default=EmailTransportMode.CLOUD,
+    )
+
+    # SMTP transport parameters (unused when transport_mode == CLOUD).
+    host = models.CharField(max_length=255, blank=True, default="")
+    port = models.PositiveIntegerField(default=587)
+    security = models.CharField(
+        max_length=8,
+        choices=EmailSecurity.choices,
+        default=EmailSecurity.TLS,
+    )
+    username = models.CharField(max_length=255, blank=True, default="")
+    # Fernet-encrypted SMTP password / provider API key. Never serialized out.
+    password_ciphertext = models.BinaryField(blank=True, default=b"")
+
+    # From identity + deliverability.
+    from_name = models.CharField(max_length=255, blank=True, default="")
+    from_email = models.EmailField(blank=True, default="")
+    reply_to = models.EmailField(blank=True, default="")
+    dkim_selector = models.CharField(max_length=63, blank=True, default="")
+
+    # Delivery limits. throttle_per_min == 0 means "no throttle".
+    max_recipients = models.PositiveIntegerField(default=50)
+    throttle_per_min = models.PositiveIntegerField(default=0)
+
+    # Bounce webhook — NOT WIRED. Removed from the serializer and the Email
+    # settings UI in #2860: there is no bounce-ingest endpoint anywhere in this
+    # app, and nothing has ever POSTed to this URL or read it back. It persisted,
+    # validated through the SSRF egress guard, rendered back and was documented,
+    # which is exactly what made it look like a working control.
+    #
+    # The column is RETAINED rather than dropped so no operator's stored value is
+    # destroyed; #2872 builds the ingest endpoint and re-exposes the field. Do not
+    # re-add it to the serializer before that lands.
+    bounce_webhook_url = models.URLField(max_length=512, blank=True, default="")
+
+    updated_at = models.DateTimeField(auto_now=True)
+    updated_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="+",
+    )
+
+    class Meta:
+        db_table = "notifications_workspace_email_settings"
+        verbose_name = "workspace email settings"
+        verbose_name_plural = "workspace email settings"
+
+    def __str__(self) -> str:
+        return f"WorkspaceEmailSettings(transport={self.transport_mode})"
+
+    @classmethod
+    def load(cls) -> WorkspaceEmailSettings:
+        """Return the singleton, creating it on first access (no seed migration)."""
+        obj, _ = cls.objects.get_or_create(singleton_key=1)
+        return obj
+
+    @property
+    def password_is_set(self) -> bool:
+        """Whether an encrypted SMTP password is stored (safe to expose)."""
+        return bool(self.password_ciphertext)
+
+    def set_password(self, plaintext: str) -> None:
+        """Fernet-encrypt and store the SMTP password / provider API key.
+
+        An empty ``plaintext`` clears the stored secret. Callers that want the
+        "blank means keep existing" semantics must guard before calling this —
+        the serializer does (#712 rotate-vs-keep).
+        """
+        from trueppm_api.apps.integrations.encryption import encrypt_secret
+
+        if not plaintext:
+            self.password_ciphertext = b""
+            return
+        self.password_ciphertext = encrypt_secret(plaintext)
+
+    def get_password(self) -> str:
+        """Decrypt and return the stored password, or "" when none is set."""
+        if not self.password_ciphertext:
+            return ""
+        from trueppm_api.apps.integrations.encryption import decrypt_secret
+
+        return decrypt_secret(bytes(self.password_ciphertext))