trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/config_notice.py

@@ -0,0 +1,1330 @@
+"""Config-change notice: a change to the shared surface tells everyone on it (#2972).
+
+Removing a board lane, hiding a column or a leaf surface, or switching the
+methodology preset changes the surface **every assignee** works on. Before this,
+only the person who clicked knew — the write broadcast ``board_config_updated``
+to whoever happened to have the board open, and nothing reached anyone else.
+
+Three properties, and the second is the one most likely to be eroded later:
+
+1. **It fires on the consequence, not the write.** A rename, a color, a WIP limit,
+   an added lane, a reorder — none of these notify. Only a change that moves or
+   hides work does. A notice on every save is noise, and noise gets muted, which
+   costs the signal this exists to carry. This is why the leaf-surface arm speaks
+   only for :data:`ENFORCED_SURFACE_KEYS`: a toggle no client reads moves nothing
+   on screen, so announcing it is the write talking, not the consequence (#3376).
+2. **The body names what the change did to the recipient's own items.** "Board
+   configuration updated" is precisely the notification this module exists to
+   refuse. Each recipient's row is rendered for them, with their own count, and
+   the batch is written in one insert — ``create_event_notifications_batch`` for
+   the board notice, its project-spanning form for the surface notice.
+3. **It reaches everyone the change re-shapes, not just the actor.** For the
+   board notice that is everyone with work on the board: the union of
+   ``Task.assignee`` and ``TaskResource`` over the project — see
+   :func:`assigned_recipient_ids` for why it is the union and not either one
+   alone — intersected with live membership. For the **surface** notice it is
+   wider, because assignment is the wrong proxy for "this surface is yours":
+   :func:`surface_recipient_ids` adds the ADR-0078 facet holders and everyone
+   seated at ``role >= SCHEDULER`` (#3291).
+
+Never dispatched from a refusal path. Under ``ATOMIC_REQUESTS`` DRF's exception
+handler calls ``set_rollback()`` for every ``APIException``, which discards the
+whole transaction *including* its ``on_commit`` callbacks — so a notice attached
+to a rejected write would be silently dropped anyway. Every entry point here is
+called after a successful ``save()``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections import Counter
+from functools import partial
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from celery.exceptions import SoftTimeLimitExceeded
+from django.db import transaction
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .models import Project
+
+logger = logging.getLogger(__name__)
+
+#: Human labels for the four leaf surfaces (``surface_visibility.SURFACE_KEYS``).
+#: Kept here rather than derived from the key so the notice reads as product copy
+#: ("Monte Carlo") rather than as a column name ("monte_carlo"). The map stays
+#: complete even though ``time_tracking`` is currently unreachable through
+#: :data:`ENFORCED_SURFACE_KEYS` — restoring that key is then a one-line change
+#: rather than a re-derivation.
+SURFACE_LABELS: dict[str, str] = {
+    "reporting": "Reporting",
+    "time_tracking": "Time tracking",
+    "baselines": "Baselines",
+    "monte_carlo": "Monte Carlo",
+}
+
+#: The surfaces whose visibility a client actually acts on — the subset of
+#: ``SURFACE_KEYS`` this module is allowed to speak about.
+#:
+#: ``time_tracking`` is deliberately absent (#3376). Nothing on web or mobile
+#: reads ``Project.show_time_tracking``, so hiding it moves nothing on anyone's
+#: screen — yet the notice told every assigned member, every facet holder and
+#: every Scheduler+ seat that "Dana hid Time tracking in this project." That is
+#: property 1 of this module inverted: it fired on the *write* rather than on the
+#: consequence, and a notice about a change with no consequence is exactly the
+#: noise that gets the signal muted.
+#:
+#: Filtering here rather than in the copy is deliberate — it is the single choke
+#: point. :func:`capture_project_surface` builds both snapshots, so restricting it
+#: suppresses the clause AND stops a time-tracking-only flip from being a
+#: :class:`SurfaceChange` at all (which would otherwise emit a notice whose only
+#: remaining sentence is "Nothing you own moved."). Add the key back the day a
+#: surface reads the flag; see ``Project.show_time_tracking``.
+#:
+#: **Known hole, tracked as #3400.** This set is the has-a-consumer fact, and it
+#: lives here — client-side of the API — so the REST surface still serves
+#: ``effective_surface_visibility.time_tracking`` as a bare boolean an agent reads
+#: as a real answer. #3400 moves the fact beside ``SURFACE_KEYS`` and serves it,
+#: which also collapses the three places that must currently be edited in lockstep
+#: (this set, the settings page's ``notEnforced`` string, and the docs section)
+#: into one. Do not add a fourth unbound copy; extend #3400 instead.
+#:
+#: Pinned against the live ``SURFACE_KEYS`` by ``test_config_change_notice``'s
+#: ``test_the_notice_speaks_for_every_surface_except_the_one_with_no_reader`` —
+#: an allowlist omits a NEW key by default, and that failure is silent.
+ENFORCED_SURFACE_KEYS: frozenset[str] = frozenset({"reporting", "baselines", "monte_carlo"})
+
+#: Projects whose surface notices are resolved, rendered and written together.
+#:
+#: The reads are batched, so on query count alone the best chunk is the whole
+#: apply — two hundred projects for eight reads. This trades a little of that
+#: (four passes instead of one for a max-size apply, against ~1,800 before the
+#: batching) for two bounds one flat batch does not have:
+#:
+#: * **Peak memory.** The rendered ``rows`` list holds a subject and a body
+#:   string per recipient. Flat, that is the sum over the whole apply; chunked it
+#:   is the maximum over one chunk.
+#: * **Blast radius.** The reads and the insert sit under one ``try``, so a
+#:   failure in either loses every project that shares it. Flat, one bad read
+#:   drops the whole apply's notices; chunked it drops one chunk's.
+#:
+#: Fifty is the size at which the two bounds in play agree rather than one
+#: dominating: a chunk of fifty projects at a typical ten-recipient cohort
+#: renders ~500 rows, which is exactly ``NOTIFICATION_BULK_BATCH_SIZE`` — so the
+#: list being accumulated and the statement it becomes are capped at the same
+#: order of magnitude, and neither bound is doing all the work alone.
+SURFACE_EMIT_CHUNK_SIZE = 50
+
+
+def _chunked(items: Sequence[SurfaceChange], size: int) -> list[Sequence[SurfaceChange]]:
+    """``items`` split into consecutive runs of at most ``size``.
+
+    ``itertools.batched`` is the stdlib answer and this is not it, deliberately:
+    the runtime floor is Python 3.12 but ``[tool.mypy] python_version`` is 3.11,
+    where the stubs have no ``batched`` and ``mypy --strict`` fails. Widening a
+    global type-checker setting to import one helper is the wrong trade.
+    """
+    return [items[start : start + size] for start in range(0, len(items), size)]
+
+
+#: Human labels for the methodology preset values.
+METHODOLOGY_LABELS: dict[str, str] = {
+    "WATERFALL": "Waterfall",
+    "AGILE": "Agile",
+    "HYBRID": "Hybrid",
+}
+
+
+# ---------------------------------------------------------------------------
+# Recipients — "everyone assigned in the project"
+# ---------------------------------------------------------------------------
+
+
+def _assigned_candidates_by_project(project_ids: Sequence[Any]) -> dict[str, set[Any]]:
+    """``{str(project_id): {user_id, ...}}`` — everyone with work, for a batch.
+
+    Two queries for any number of projects, which is the whole point: the union
+    of ``Task.assignee`` and ``TaskResource.resource.user`` is the same pair of
+    reads whether it is asked of one project or two hundred, and asking it per
+    project inside a bulk apply is how the emit reached ~2,000 round-trips
+    (#3335). :func:`assigned_recipient_ids` is the one-project caller.
+
+    Keys are stringified because the ids that reach here travel through an
+    ``on_commit`` payload as ``str``, while the ORM yields ``uuid.UUID`` — a
+    mapping keyed on the raw column would silently miss every lookup.
+
+    ``.distinct()`` matters on both arms: without it Postgres streams one row per
+    TASK to build a set of maybe thirty user ids, so a 10k-task project pulls 10k
+    UUIDs over the wire twice. The de-dupe belongs in the database.
+
+    **``.order_by()`` is what makes that ``.distinct()`` real, and it is not
+    cosmetic.** ``Task.Meta.ordering`` is ``["wbs_path", "name"]``, and a
+    ``.distinct()`` with no ``distinct_fields`` promotes every ORDER BY column
+    into the SELECT list — so the statement becomes ``SELECT DISTINCT project_id,
+    assignee_id, wbs_path, name``. ``projects_task`` carries an
+    ``ExclusionConstraint`` on ``(project, wbs_path)`` over live rows, which makes
+    that tuple unique among exactly the rows being scanned, so the DISTINCT
+    matches nothing and returns one row per task — the de-dupe silently does not
+    happen. Clearing the default ordering is the only thing standing between this
+    and the full-table transfer the previous paragraph exists to prevent.
+    """
+    from trueppm_api.apps.resources.models import TaskResource
+
+    from .models import Task
+
+    by_project: dict[str, set[Any]] = {}
+    for project_id, user_id in (
+        Task.objects.filter(project_id__in=project_ids, is_deleted=False)
+        .exclude(assignee_id=None)
+        .order_by()
+        .values_list("project_id", "assignee_id")
+        .distinct()
+    ):
+        by_project.setdefault(str(project_id), set()).add(user_id)
+    for project_id, user_id in (
+        # `TaskResource.Meta.ordering` is empty today, so this `order_by()` is a
+        # no-op — kept so that giving the model a default ordering later cannot
+        # quietly defeat this `distinct()` the way it does the Task arm above.
+        TaskResource.objects.filter(task__project_id__in=project_ids, task__is_deleted=False)
+        .exclude(resource__user__isnull=True)
+        .order_by()
+        .values_list("task__project_id", "resource__user_id")
+        .distinct()
+    ):
+        by_project.setdefault(str(project_id), set()).add(user_id)
+    return by_project
+
+
+def assigned_recipient_ids(
+    project_id: Any,
+    *,
+    exclude_user_id: Any = None,
+    live_member_ids: set[Any] | None = None,
+) -> list[Any]:
+    """User ids of everyone with work in ``project_id``, minus the actor.
+
+    The board notice's cohort, and the assignment-shaped half of
+    :func:`surface_recipient_ids`. A lane going away moves *cards*, so having a
+    card is what makes someone a recipient — the wider surface cohort is not
+    right here, because a Product Owner with no card on the board has had nothing
+    moved out from under them.
+
+    The **union** of ``Task.assignee`` and ``TaskResource.resource.user``,
+    deliberately — and this is the one place in the codebase where the union is
+    right rather than one or the other. ``notify_amend`` uses ``TaskResource``
+    alone because it is talking about committed *load*, and a bare assignee
+    carries none. This is about the board a person works on, and a bare assignee
+    looks at exactly the same board as a resourced one; using ``TaskResource``
+    alone would silently tell nobody in a project imported from Jira (which
+    writes neither) or seeded from a template (assignees, no assignments).
+
+    Intersected with live ``ProjectMembership`` (``is_deleted=False``): an inbox
+    row about a project the recipient can no longer open is a dead link, and
+    naming a project's internal structure to a removed member is a scope leak
+    (ADR-0104's back-door close — a non-member sits below every tier).
+
+    ``live_member_ids`` lets a caller that has already read the project's live
+    membership pass it in rather than making this run the same filter a second
+    time — :func:`surface_recipient_ids` needs the full ``(user_id, role)`` map
+    for its own cohorts, and that map is a strict superset of the answer this
+    liveness check would compute for itself. Defaulted to ``None`` so the board
+    call site stays self-contained.
+    """
+    from trueppm_api.apps.access.models import ProjectMembership
+
+    candidates = set(_assigned_candidates_by_project([project_id]).get(str(project_id), set()))
+    candidates.discard(None)
+    if exclude_user_id is not None:
+        candidates.discard(exclude_user_id)
+    if not candidates:
+        return []
+
+    live_members = (
+        live_member_ids
+        if live_member_ids is not None
+        else set(
+            ProjectMembership.objects.filter(
+                project_id=project_id, is_deleted=False, user_id__in=candidates
+            ).values_list("user_id", flat=True)
+        )
+    )
+    return sorted(candidates & live_members, key=str)
+
+
+def surface_recipient_ids(project_id: Any, *, exclude_user_id: Any = None) -> list[Any]:
+    """User ids of everyone a surface change re-shapes in ``project_id``, minus the actor.
+
+    Three cohorts, unioned:
+
+    1. everyone with work in the project — :func:`assigned_recipient_ids`;
+    2. the ADR-0078 Scrum Master and Product Owner facet holders;
+    3. ``ProjectMembership`` rows at ``role >= Role.SCHEDULER``.
+
+    Assignment alone is the wrong proxy for "this surface is yours" (#3291). A
+    Product Owner authors and prioritizes the backlog and is frequently assigned
+    none of it; a Scrum Master facilitates and is neither an assignee nor a booked
+    resource; a PM who owns the plan routinely assigns none of it to themselves.
+    Those are the three people a preset flip re-shapes hardest, and the ones
+    everyone else asks to explain it — and the assigned-only cohort excluded
+    exactly them. Same class as #2897 at a new sink, which is why the facet half
+    reads :func:`~trueppm_api.apps.teams.services.facet_holder_user_ids` — the
+    scope gate's own source — rather than reimplementing the team lookup here.
+
+    The two sinks are ``ProjectViewSet.perform_update`` (gated ``IsProjectScheduler``)
+    and the program bulk matrix (gated ``IsProgramAdmin`` — a program-level gate with
+    no project-role correspondence at all). ``role >= SCHEDULER`` therefore sits *at
+    or below* the write gate on both paths rather than mirroring either, and the
+    threshold is justified by **read** parity, not write parity: ``show_*`` and
+    ``effective_surface_visibility`` are already readable by any project member
+    (Viewer+), so telling a Scheduler discloses nothing they could not fetch
+    themselves. Note the cohort is deliberately not role-monotone — the facet arm
+    notifies Member- and Viewer-seated holders, per ADR-0078 and #2897.
+
+    **Every cohort is intersected with live ``ProjectMembership``**, and the facet
+    half genuinely needs it: the ADR-0078 §F mirror only ever *creates* team rows
+    (:mod:`trueppm_api.apps.teams.signals` has no ``post_delete`` receiver and
+    ``TeamMembership`` has no FK a cascade could travel), so soft-deleting a
+    ``ProjectMembership`` leaves the mirrored ``TeamMembership`` live with its
+    facet flags intact. Without the intersection, widening the cohort would widen
+    who keeps being told a project's internal structure after losing access — a
+    dead link and a scope leak (ADR-0104's back-door close: a non-member sits
+    below every tier).
+
+    The two sibling facet cohorts leaked on exactly that path until #3334 moved the
+    guard into ``facet_holder_user_ids`` itself, where it is now the default for
+    every caller — :func:`~trueppm_api.apps.projects.services._sprint_lead_recipient_ids`
+    and :func:`~trueppm_api.apps.projects.blocker_services.resolve_impediment_recipients`
+    get it without asking. This function opts *out* of the helper's own subquery
+    (``live_project_members_only=False``) precisely because it has already read live
+    membership and intersects in Python — see the paragraph below.
+
+    One membership read serves all three cohorts: the ``(user_id, role)`` map is
+    the Scheduler+ set, the facet arm's liveness floor, **and** the liveness floor
+    :func:`assigned_recipient_ids` would otherwise query for itself — which is why
+    it is threaded in rather than letting that call repeat the same filter.
+
+    The actor is discarded **after** the union, not before it, and that order is
+    load-bearing: the actor of a surface change is Scheduler+ on the
+    ``perform_update`` path essentially by definition, so the Scheduler arm re-adds
+    them on every flip. This final ``discard`` is the only thing standing between a
+    PM and a notice about their own click.
+
+    Implemented by :func:`surface_recipient_ids_by_project` with a one-element
+    batch — same four queries, one definition of the cohort.
+    """
+    return surface_recipient_ids_by_project([project_id], exclude_user_id=exclude_user_id).get(
+        str(project_id), []
+    )
+
+
+def surface_recipient_ids_by_project(
+    project_ids: Sequence[Any], *, exclude_user_id: Any = None
+) -> dict[str, list[Any]]:
+    """``{str(project_id): [user_id, ...]}`` — the surface cohort, for a batch.
+
+    Four queries for any number of projects, and exactly the four
+    :func:`surface_recipient_ids` used to issue for one: the membership scan, the
+    two assignment reads and the facet join. Each is ``project_id IN (...)``
+    grouped by project, and nothing in the batch depends on another project's
+    result, so the per-project loop that used to hold them belongs above them
+    rather than around them (#3335).
+
+    Cohort semantics, liveness and actor exclusion are :func:`surface_recipient_ids`'s
+    — read that docstring; this is the same function asked of a set of projects,
+    and the single-project form now delegates here so the two cannot drift.
+
+    The facet arm reads :func:`~trueppm_api.apps.teams.services.facet_holder_user_ids_by_project`,
+    the batch counterpart of the scope gate's own source, and intersects it with
+    ``live_ids`` here — the same intersection the one-project path applied, from
+    the same membership map, so widening the batch cannot widen who keeps being
+    told a project's internal structure after losing access.
+    """
+    from trueppm_api.apps.access.models import ProjectMembership, Role
+    from trueppm_api.apps.teams.services import facet_holder_user_ids_by_project
+
+    live_roles: dict[str, dict[Any, int]] = {}
+    for project_id, user_id, role in ProjectMembership.objects.filter(
+        project_id__in=project_ids, is_deleted=False
+    ).values_list("project_id", "user_id", "role"):
+        live_roles.setdefault(str(project_id), {})[user_id] = role
+
+    assigned = _assigned_candidates_by_project(project_ids)
+    facets = {
+        str(pid): holders for pid, holders in facet_holder_user_ids_by_project(project_ids).items()
+    }
+
+    cohorts: dict[str, list[Any]] = {}
+    for raw_id in project_ids:
+        pid = str(raw_id)
+        roles = live_roles.get(pid, {})
+        live_ids = set(roles)
+
+        recipients = assigned.get(pid, set()) & live_ids
+        recipients |= {uid for uid, role in roles.items() if role >= Role.SCHEDULER}
+        recipients |= facets.get(pid, set()) & live_ids
+
+        recipients.discard(None)
+        if exclude_user_id is not None:
+            recipients.discard(exclude_user_id)
+        cohorts[pid] = sorted(recipients, key=str)
+    return cohorts
+
+
+def _counts_by_user(project_id: Any, task_filter: Any) -> Counter[Any]:
+    """Per-user count of the affected tasks in ``project_id``.
+
+    Two **grouped** queries, and no per-task rows materialized in Python. The
+    surface path passes a bare ``Q()`` — every task in the project — so pulling
+    ``(user, task)`` pairs back to de-duplicate them would build a set
+    proportional to the whole task table on a project that could have tens of
+    thousands of rows, to produce a handful of integers.
+
+    A task the same user both owns and is booked on must count **once**, which is
+    what the ``F("task__assignee_id")`` exclusion does: the assignee side counts
+    every owned task, and the resource side counts only the ones the counter does
+    not already own. ``distinct=True`` belongs on the **resource** arm only, where
+    a user booked twice on one task through two resource rows would otherwise
+    count twice; the assignee arm groups by ``assignee_id`` over a join-free
+    queryset, so its ``id`` is already unique per group.
+
+    Implemented by :func:`_counts_by_user_by_project` with a one-element batch —
+    still two queries, one definition of the count.
+    """
+    return _counts_by_user_by_project([project_id], task_filter).get(str(project_id), Counter())
+
+
+def _counts_by_user_by_project(
+    project_ids: Sequence[Any], task_filter: Any
+) -> dict[str, Counter[Any]]:
+    """``{str(project_id): Counter({user_id: n})}`` — :func:`_counts_by_user`, batched.
+
+    Two **grouped** queries for any number of projects: the grouping key gains
+    ``project_id`` and the filter becomes ``IN (...)``, which is the entire
+    difference. The surface notice runs this once per bulk apply rather than once
+    per project (#3335), and every de-duplication rule described above is
+    unchanged — ``project_id`` only partitions groups a single project's query
+    already kept separate, since a task belongs to exactly one project.
+    """
+    from django.db.models import Count, F
+
+    from trueppm_api.apps.resources.models import TaskResource
+
+    from .models import Task
+
+    affected = Task.objects.filter(project_id__in=project_ids, is_deleted=False).filter(task_filter)
+    counts: dict[str, Counter[Any]] = {}
+    for pid, uid, n in (
+        affected.exclude(assignee_id=None)
+        .values("project_id", "assignee_id")
+        .annotate(n=Count("id"))
+        .values_list("project_id", "assignee_id", "n")
+    ):
+        counts.setdefault(str(pid), Counter())[uid] += n
+    for pid, uid, n in (
+        TaskResource.objects.filter(task__in=affected)
+        .exclude(resource__user__isnull=True)
+        .exclude(resource__user_id=F("task__assignee_id"))
+        .values("task__project_id", "resource__user_id")
+        .annotate(n=Count("task_id", distinct=True))
+        .values_list("task__project_id", "resource__user_id", "n")
+    ):
+        counts.setdefault(str(pid), Counter())[uid] += n
+    return counts
+
+
+def _actor_name(actor: Any) -> str:
+    """Display name for the person who made the change, or a neutral stand-in."""
+    if actor is None or not getattr(actor, "is_authenticated", False):
+        return "Someone"
+    return (
+        getattr(actor, "get_full_name", lambda: "")() or getattr(actor, "username", "") or "Someone"
+    )
+
+
+def _actor_id(actor: Any) -> Any:
+    return actor.pk if actor is not None and getattr(actor, "is_authenticated", False) else None
+
+
+def _plural(count: int, singular: str = "item", plural: str = "items") -> str:
+    return f"{count} {singular if count == 1 else plural}"
+
+
+# ---------------------------------------------------------------------------
+# Board configuration — lanes removed, columns hidden
+# ---------------------------------------------------------------------------
+
+
+class _RemovedLane(NamedTuple):
+    key: str
+    label: str
+    column_label: str
+    destination: str
+
+
+class _HiddenColumn(NamedTuple):
+    status: str
+    label: str
+
+
+def _column_label(column: dict[str, Any]) -> str:
+    return str(column.get("label") or column.get("status") or "this column")
+
+
+def _first_lane_label(column: dict[str, Any] | None) -> str:
+    """Where an orphaned lane key lands, said in words.
+
+    ``Task.board_lane`` is never rewritten when a lane is deleted (a bulk UPDATE
+    would bypass the ``server_version`` bump every synced write depends on), so
+    the board resolves a dangling key to the column's **first** lane on read. The
+    notice must name the same destination the board will actually show, or it
+    describes a move that did not happen.
+    """
+    if column is None:
+        return "its column"
+    lanes = column.get("lanes") or []
+    if lanes:
+        first = lanes[0]
+        return str(first.get("label") or first.get("key") or "the first lane")
+    # No lanes left at all: the column renders as one implicit lane, i.e. itself.
+    return _column_label(column)
+
+
+def _removed_lanes(
+    old_by_status: dict[str, dict[str, Any]],
+    new_by_status: dict[str, dict[str, Any]],
+) -> list[_RemovedLane]:
+    """Lanes that existed before the write and do not survive it.
+
+    Each one carries the destination its orphaned cards will resolve to, read
+    from the *new* column — see :func:`_first_lane_label`.
+    """
+    removed: list[_RemovedLane] = []
+    for status, old_col in old_by_status.items():
+        new_col = new_by_status.get(status)
+        surviving = {str(lane.get("key")) for lane in (new_col or {}).get("lanes") or []}
+        for lane in old_col.get("lanes") or []:
+            key = str(lane.get("key"))
+            if key in surviving:
+                continue
+            removed.append(
+                _RemovedLane(
+                    key=key,
+                    label=str(lane.get("label") or key),
+                    column_label=_column_label(new_col or old_col),
+                    destination=_first_lane_label(new_col),
+                )
+            )
+    return removed
+
+
+def _hidden_columns(
+    old_by_status: dict[str, dict[str, Any]],
+    new_by_status: dict[str, dict[str, Any]],
+) -> list[_HiddenColumn]:
+    """Columns that were visible before the write and are not after it."""
+    hidden: list[_HiddenColumn] = []
+    for status, old_col in old_by_status.items():
+        new_col = new_by_status.get(status)
+        was_visible = old_col.get("visible", True)
+        # A column dropped from the payload entirely cannot happen (the serializer
+        # requires all five canonical statuses), but treat absence as hidden
+        # rather than as "unchanged" so the notice can never under-report.
+        now_visible = new_col.get("visible", True) if new_col is not None else False
+        if was_visible and not now_visible:
+            hidden.append(_HiddenColumn(status=status, label=_column_label(new_col or old_col)))
+    return hidden
+
+
+def diff_board_config(
+    old_columns: list[dict[str, Any]], new_columns: list[dict[str, Any]]
+) -> tuple[list[_RemovedLane], list[_HiddenColumn]]:
+    """The two board changes that move or hide work.
+
+    Everything else a board-config PUT can carry — rename, reorder, recolor, a
+    WIP-limit change, an *added* lane, a column being *un*-hidden — leaves every
+    card exactly where the person who owns it last saw it, and produces no
+    notice. Returning the pair (rather than a bool) is what lets the body name
+    the specific lane and column instead of the fact that a PUT happened.
+    """
+    new_by_status = {str(c.get("status")): c for c in new_columns}
+    old_by_status = {str(c.get("status")): c for c in old_columns}
+    return (
+        _removed_lanes(old_by_status, new_by_status),
+        _hidden_columns(old_by_status, new_by_status),
+    )
+
+
+def _removed_clause(actor_name: str, removed: list[_RemovedLane], lane_count: int) -> str:
+    """The removed-lane sentence pair, or ``""`` when no lane was removed.
+
+    Every destination is named against the lane it belongs to. Removing two lanes
+    from two different columns sends their cards to two *different* first lanes,
+    so a single destination borrowed from ``removed[0]`` would send most of the
+    recipient to the wrong place — which is worse than saying nothing, because
+    they will look there, not find their work, and stop trusting the next notice.
+    """
+    if not removed:
+        return ""
+    if len(removed) == 1:
+        lane = removed[0]
+        lead = f"{actor_name} removed the “{lane.label}” lane from {lane.column_label}."
+        tail = (
+            f"Your {_plural(lane_count)} in there now "
+            f"{'shows' if lane_count == 1 else 'show'} in “{lane.destination}” — "
+            f"the first lane of that column."
+            if lane_count
+            else "None of your items were in it."
+        )
+    else:
+        moves = _join_phrases(
+            [
+                f"“{lane.label}” from {lane.column_label} (cards move to “{lane.destination}”)"
+                for lane in removed
+            ]
+        )
+        lead = f"{actor_name} removed {len(removed)} lanes: {moves}."
+        tail = (
+            f"{lane_count} of those items {'is' if lane_count == 1 else 'are'} yours."
+            if lane_count
+            else "None of your items were in them."
+        )
+    return f"{lead} {tail}"
+
+
+def _hidden_clause(actor_name: str, hidden: list[_HiddenColumn], column_count: int) -> str:
+    """The hidden-column sentence pair, or ``""`` when no column was hidden."""
+    if not hidden:
+        return ""
+    names = _join_phrases([f"“{col.label}”" for col in hidden])
+    noun = "column" if len(hidden) == 1 else "columns"
+    lead = f"{actor_name} hid the {names} {noun}."
+    if column_count:
+        # NOT "reach them from My Work": `/me/work/` filters on `assignee` alone
+        # and excludes BACKLOG, so that instruction is false for anyone counted
+        # through a TaskResource booking, and false for everyone when the hidden
+        # column is Backlog. A notice that sends the reader somewhere their work
+        # is not is the failure this whole module is written to avoid — so it
+        # names the two surfaces that show every status and both assignment kinds.
+        it_them = "it" if column_count == 1 else "them"
+        return (
+            f"{lead} Your {_plural(column_count)} with that status "
+            f"{'keeps its' if column_count == 1 else 'keep their'} status and dates, "
+            f"but the board no longer shows {it_them} — find {it_them} in the "
+            f"task list or search."
+        )
+    return f"{lead} None of your items have that status."
+
+
+def _board_body(
+    actor_name: str,
+    removed: list[_RemovedLane],
+    hidden: list[_HiddenColumn],
+    lane_count: int,
+    column_count: int,
+) -> str:
+    """One recipient's copy of the board notice."""
+    parts = [
+        _removed_clause(actor_name, removed, lane_count),
+        _hidden_clause(actor_name, hidden, column_count),
+    ]
+    return " ".join(part for part in parts if part)
+
+
+def _join_phrases(phrases: list[str]) -> str:
+    """``a``, ``a and b``, ``a, b and c`` — an Oxford-comma-free serial list."""
+    if len(phrases) == 1:
+        return phrases[0]
+    return f"{', '.join(phrases[:-1])} and {phrases[-1]}"
+
+
+def _board_subject(removed: list[_RemovedLane], hidden: list[_HiddenColumn], affected: int) -> str:
+    """A subject that already carries the consequence.
+
+    The inbox row previews the body, but the subject is what a recipient scanning
+    a full bell sees first — so it states what happened to *them*, not that a
+    configuration changed.
+    """
+    if removed and hidden:
+        return (
+            f"Your board was reconfigured — {_plural(affected)} affected"
+            if affected
+            else "Your board was reconfigured"
+        )
+    if removed:
+        what = (
+            "A board lane was removed"
+            if len(removed) == 1
+            else f"{len(removed)} board lanes were removed"
+        )
+        return f"{what} — {_plural(affected)} moved" if affected else what
+    what = (
+        "A board column was hidden"
+        if len(hidden) == 1
+        else f"{len(hidden)} board columns were hidden"
+    )
+    return f"{what} — {_plural(affected)} no longer on the board" if affected else what
+
+
+def notify_board_config_change(
+    project: Project,
+    *,
+    old_columns: list[dict[str, Any]],
+    new_columns: list[dict[str, Any]],
+    actor: Any,
+) -> None:
+    """Tell everyone with work in ``project`` that a lane or column went away.
+
+    Queued through the ``ConfigNoticeRequest`` outbox (ADR-1174) and emitted by a
+    worker: a notification failure must never revert a board configuration the
+    caller has already accepted, and must not be lost to a broker outage either.
+
+    **Every read the notice depends on happens in the worker** — the recipient set
+    as well as the counts. Resolving recipients here instead would run three
+    queries while the caller still holds its write locks, and would pair a
+    pre-commit recipient list with post-commit counts, so a person whose
+    assignment changed in the window could get a row whose count describes a
+    different moment than the list that selected them.
+    """
+    removed, hidden = diff_board_config(old_columns, new_columns)
+    if not removed and not hidden:
+        return
+
+    _enqueue(
+        KIND_BOARD,
+        {
+            "project_id": str(project.pk),
+            "actor_name": _actor_name(actor),
+            "removed": [lane._asdict() for lane in removed],
+            "hidden": [column._asdict() for column in hidden],
+        },
+        actor=actor,
+    )
+
+
+def _emit_board_notifications(
+    project_id: str,
+    actor_id: Any,
+    removed: list[_RemovedLane],
+    hidden: list[_HiddenColumn],
+    actor_name: str,
+) -> None:
+    from django.db.models import Q
+
+    from trueppm_api.apps.notifications.models import NotificationEventType
+    from trueppm_api.apps.notifications.services import create_event_notifications_batch
+
+    try:
+        recipient_ids = assigned_recipient_ids(project_id, exclude_user_id=actor_id)
+        if not recipient_ids:
+            return
+
+        lane_counts: Counter[Any] = Counter()
+        if removed:
+            lane_counts = _counts_by_user(
+                project_id, Q(board_lane__in=[lane.key for lane in removed])
+            )
+        column_counts: Counter[Any] = Counter()
+        if hidden:
+            column_counts = _counts_by_user(
+                project_id, Q(status__in=[col.status for col in hidden])
+            )
+
+        rows = []
+        for rid in recipient_ids:
+            lane_n = lane_counts.get(rid, 0)
+            column_n = column_counts.get(rid, 0)
+            rows.append(
+                (
+                    rid,
+                    _board_subject(removed, hidden, lane_n + column_n),
+                    _board_body(actor_name, removed, hidden, lane_n, column_n),
+                    None,
+                )
+            )
+        create_event_notifications_batch(
+            event_type=NotificationEventType.PROJECT_CONFIG_CHANGED,
+            project_id=project_id,
+            rows=rows,
+        )
+    except Exception:
+        logger.exception("notify_board_config_change: emit failed for project %s", project_id)
+
+
+# ---------------------------------------------------------------------------
+# Project preset and leaf-surface visibility
+# ---------------------------------------------------------------------------
+
+
+class ProjectSurfaceSnapshot(NamedTuple):
+    """The project's surface as it stood before a write.
+
+    Captured rather than re-read because ``serializer.save()`` mutates the
+    instance in place — after it, the previous preset is unrecoverable.
+    """
+
+    methodology: str
+    #: Effective visibility keyed by surface, restricted to
+    #: :data:`ENFORCED_SURFACE_KEYS` — NOT every key in ``SURFACE_KEYS``.
+    visibility: dict[str, bool]
+    #: The surfaces :data:`ENFORCED_SURFACE_KEYS` leaves out. Captured for ONE
+    #: purpose — the diagnostic in :func:`collect_project_surface_change` — and
+    #: deliberately excluded from the change comparison, so it can never
+    #: resurrect the notice it exists to explain the absence of. Defaults to
+    #: empty for hand-built test snapshots; never mutated, so the shared default
+    #: is safe.
+    unenforced: dict[str, bool] = {}  # noqa: RUF012
+
+
+def capture_project_surface(project: Project, *, workspace: Any = None) -> ProjectSurfaceSnapshot:
+    """Snapshot ``project``'s preset and its *enforced* leaf-surface visibility.
+
+    Narrowed to :data:`ENFORCED_SURFACE_KEYS`, so the snapshot carries only the
+    surfaces a client actually renders against. A surface nothing reads cannot
+    make the before/after differ, and therefore cannot produce a notice — which
+    is the whole guarantee, applied once here rather than restated in the diff
+    and again in the copy.
+    """
+    from .surface_visibility import resolve_effective_visibility
+
+    resolved = resolve_effective_visibility(project, workspace=workspace)
+    return ProjectSurfaceSnapshot(
+        methodology=str(project.methodology or ""),
+        visibility={k: v for k, v in resolved.items() if k in ENFORCED_SURFACE_KEYS},
+        unenforced={k: v for k, v in resolved.items() if k not in ENFORCED_SURFACE_KEYS},
+    )
+
+
+def _is_are(count: int) -> str:
+    return "is" if count == 1 else "are"
+
+
+def _attribution_clauses(
+    actor_name: str,
+    before: ProjectSurfaceSnapshot,
+    after: ProjectSurfaceSnapshot,
+) -> list[str]:
+    """The preset clause and the surface clauses, in that order.
+
+    The actor is named exactly once, and which clause names them is load-bearing
+    — which is why both sides of the preset-vs-override split live in this one
+    function rather than in two. A preset switch is the deliberate act and the
+    surface changes fall out of it, so the preset clause is attributed and the
+    surfaces are stated as consequence: writing "Dana hid Baselines" for a flip
+    Dana never made surface-by-surface would attribute a decision to them that
+    they did not take. When there is no preset change the override IS the
+    deliberate act, so it takes the attribution.
+    """
+    parts: list[str] = []
+    hidden = [k for k, v in after.visibility.items() if before.visibility.get(k) and not v]
+    shown = [k for k, v in after.visibility.items() if v and not before.visibility.get(k, False)]
+
+    if before.methodology != after.methodology:
+        old_label = METHODOLOGY_LABELS.get(before.methodology, before.methodology or "none")
+        new_label = METHODOLOGY_LABELS.get(after.methodology, after.methodology)
+        parts.append(
+            f"{actor_name} switched this project's planning preset from {old_label} to {new_label}."
+        )
+        if hidden:
+            parts.append(f"{_join_labels(hidden)} {_is_are(len(hidden))} no longer shown here.")
+        if shown:
+            parts.append(f"{_join_labels(shown)} {_is_are(len(shown))} now shown.")
+    else:
+        if hidden:
+            parts.append(f"{actor_name} hid {_join_labels(hidden)} in this project.")
+        if shown:
+            parts.append(f"{actor_name} turned {_join_labels(shown)} back on in this project.")
+    return parts
+
+
+def _ownership_clause(item_count: int) -> str:
+    """The closing clause, which always speaks to the recipient's own items.
+
+    The zero branch is load-bearing rather than an edge case: once the cohort
+    includes facet holders and Scheduler+ members (:func:`surface_recipient_ids`),
+    a recipient owning nothing is the *normal* case for a PO or Scrum Master, not
+    a rarity. It stays a sentence rather than an omission because a dropped clause
+    reads as an unstated many.
+    """
+    if item_count:
+        keeps = "keeps its" if item_count == 1 else "keep their"
+        return (
+            f"Your {_plural(item_count)} {keeps} status, dates and assignments — "
+            f"what changed is where you find "
+            f"{'it' if item_count == 1 else 'them'}."
+        )
+    return "Nothing you own moved."
+
+
+def _surface_body(
+    actor_name: str,
+    before: ProjectSurfaceSnapshot,
+    after: ProjectSurfaceSnapshot,
+    item_count: int,
+) -> str:
+    """One recipient's copy of the preset / views notice.
+
+    Every clause is grounded in a value the server computed: the two preset
+    labels, and the surfaces whose *effective* visibility actually flipped. It
+    does not claim anything about which chrome the web client chooses to render
+    for a preset — a notice that over-claims is worse than a terse one, because
+    the recipient checks it once and stops believing the next one.
+    """
+    parts = _attribution_clauses(actor_name, before, after)
+    parts.append(_ownership_clause(item_count))
+    return " ".join(parts)
+
+
+def _join_labels(keys: list[str]) -> str:
+    return _join_phrases([SURFACE_LABELS.get(k, k) for k in keys])
+
+
+def _surface_subject(before: ProjectSurfaceSnapshot, after: ProjectSurfaceSnapshot) -> str:
+    if before.methodology != after.methodology:
+        new_label = METHODOLOGY_LABELS.get(after.methodology, after.methodology)
+        return f"This project now runs as {new_label}"
+    return "The views in this project changed"
+
+
+class SurfaceChange(NamedTuple):
+    """One project's before/after, ready to render once the transaction commits."""
+
+    project_id: str
+    before: ProjectSurfaceSnapshot
+    after: ProjectSurfaceSnapshot
+
+
+def collect_project_surface_change(
+    project: Project,
+    *,
+    before: ProjectSurfaceSnapshot,
+    workspace: Any = None,
+) -> SurfaceChange | None:
+    """``SurfaceChange`` if this project's surface actually moved, else ``None``.
+
+    Split out from :func:`notify_project_surface_change` so the bulk settings
+    matrix — which applies one field map to as many as ``MAX_BULK_TARGETS``
+    projects — can register **one** ``on_commit`` callback for the whole batch
+    rather than one per project. Two hundred separate callbacks would each run
+    their own recipient and count queries inline in the request/response cycle.
+
+    Returns ``None`` when the preset is unchanged and every leaf surface's
+    **effective** visibility is unchanged — so writing an explicit override equal
+    to the value the project already resolved to notifies nobody, which is right:
+    nothing on screen moved.
+    """
+    after = capture_project_surface(project, workspace=workspace)
+    if before.methodology == after.methodology and before.visibility == after.visibility:
+        # A suppressed notice is a silent non-event: an operator can see the write
+        # in ``HistoricalProject`` and see zero Notification rows, and nothing
+        # connects the two. Without this line the answer to "I hid Time tracking
+        # and nobody was told — is the notice system broken?" lives only in a
+        # frozenset in this file. Log the ONE case that is a deliberate
+        # suppression rather than a genuine no-op, so the decision is visible at
+        # the moment it takes effect (#3376).
+        moved = sorted(k for k, v in after.unenforced.items() if before.unenforced.get(k) != v)
+        if moved:
+            logger.info(
+                "surface notice suppressed for project %s: only unenforced surface(s) %s "
+                "moved — nothing reads them, so nothing on screen changed "
+                "(config_notice.ENFORCED_SURFACE_KEYS)",
+                project.pk,
+                moved,
+            )
+        return None
+    return SurfaceChange(project_id=str(project.pk), before=before, after=after)
+
+
+def notify_project_surface_change(
+    project: Project,
+    *,
+    before: ProjectSurfaceSnapshot,
+    actor: Any,
+    workspace: Any = None,
+) -> None:
+    """Tell everyone this project's surface belongs to that its preset or views moved.
+
+    The cohort is :func:`surface_recipient_ids` — wider than the board notice's,
+    because a preset flip re-shapes the working surface of people who hold no
+    assigned task.
+    """
+    change = collect_project_surface_change(project, before=before, workspace=workspace)
+    if change is None:
+        return
+    notify_surface_changes([change], actor=actor)
+
+
+def notify_surface_changes(changes: list[SurfaceChange], *, actor: Any) -> None:
+    """Queue one emit for every project whose surface moved in this transaction.
+
+    One outbox row for the whole batch, so the bulk matrix's reads stay grouped in
+    the worker exactly as #3335 grouped them in the request (ADR-1174).
+    """
+    if not changes:
+        return
+    _enqueue(
+        KIND_SURFACE,
+        {
+            "actor_name": _actor_name(actor),
+            "changes": [_surface_change_to_json(change) for change in changes],
+        },
+        actor=actor,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Outbox — the emit leaves the request (#3009, ADR-1174)
+# ---------------------------------------------------------------------------
+
+KIND_BOARD = "board"
+KIND_SURFACE = "surface"
+
+#: Claims a queued notice may take before its failure is final. Counted per claim,
+#: so a dispatch whose broker message was lost never spends the budget.
+MAX_CONFIG_NOTICE_ATTEMPTS = 3
+
+
+def _snapshot_to_json(snapshot: ProjectSurfaceSnapshot) -> dict[str, Any]:
+    return {"methodology": snapshot.methodology, "visibility": dict(snapshot.visibility)}
+
+
+def _snapshot_from_json(data: dict[str, Any]) -> ProjectSurfaceSnapshot:
+    return ProjectSurfaceSnapshot(
+        methodology=str(data["methodology"]),
+        visibility={str(k): bool(v) for k, v in data["visibility"].items()},
+    )
+
+
+def _surface_change_to_json(change: SurfaceChange) -> dict[str, Any]:
+    return {
+        "project_id": str(change.project_id),
+        "before": _snapshot_to_json(change.before),
+        "after": _snapshot_to_json(change.after),
+    }
+
+
+def _surface_change_from_json(data: dict[str, Any]) -> SurfaceChange:
+    return SurfaceChange(
+        project_id=str(data["project_id"]),
+        before=_snapshot_from_json(data["before"]),
+        after=_snapshot_from_json(data["after"]),
+    )
+
+
+def _enqueue(kind: str, payload: dict[str, Any], *, actor: Any) -> None:
+    """Write the outbox row in the caller's transaction; dispatch once it commits.
+
+    The row is the durability, not the dispatch. It commits or rolls back with the
+    config write it describes, so a notice can neither outlive a rejected write nor
+    be lost to a broker that was unreachable at the moment of commit — the drain
+    picks up whatever the on-commit dispatch could not send.
+    """
+    from .models import ConfigNoticeRequest
+
+    row = ConfigNoticeRequest.objects.create(kind=kind, payload=payload, actor_id=_actor_id(actor))
+    transaction.on_commit(partial(_dispatch_config_notice, str(row.pk)))
+
+
+def _dispatch_config_notice(request_id: str) -> None:
+    """Best-effort immediate dispatch of a committed notice.
+
+    Swallows every failure: this runs after COMMIT but still inside the request, so
+    raising here would turn a write the server already accepted into a 500. A row
+    this cannot mark ``dispatched`` stays ``pending`` and the drain sends it.
+    """
+    from django.utils import timezone
+
+    from .models import ConfigNoticeRequest, ConfigNoticeRequestStatus
+    from .tasks import emit_config_notice
+
+    try:
+        result = emit_config_notice.delay(request_id)
+        ConfigNoticeRequest.objects.filter(
+            pk=request_id, status=ConfigNoticeRequestStatus.PENDING
+        ).update(
+            status=ConfigNoticeRequestStatus.DISPATCHED,
+            celery_task_id=str(result.id),
+            claimed_at=timezone.now(),
+        )
+    except Exception:
+        logger.exception(
+            "config notice %s: immediate dispatch failed; left pending for the drain",
+            request_id,
+        )
+
+
+def run_config_notice_request(request_id: str) -> None:
+    """Claim a queued notice, apply the cooldown, and emit it.
+
+    The claim is a conditional UPDATE, so the on-commit dispatch and a drain
+    re-dispatch of the same row can race: zero rows claimed means the row is
+    running elsewhere or already finished, and this delivery is a no-op.
+
+    The emitters log and swallow their own per-chunk and per-project failures, so
+    an exception reaching this handler is structural (an unreadable payload). It
+    returns the row to ``pending`` for the drain, or marks it ``dead`` once the
+    claim budget is spent.
+    """
+    from django.db.models import F
+    from django.utils import timezone
+
+    from .models import ConfigNoticeRequest, ConfigNoticeRequestStatus
+
+    claimed = ConfigNoticeRequest.objects.filter(
+        pk=request_id,
+        status__in=[ConfigNoticeRequestStatus.PENDING, ConfigNoticeRequestStatus.DISPATCHED],
+    ).update(
+        status=ConfigNoticeRequestStatus.RUNNING,
+        claimed_at=timezone.now(),
+        attempt_count=F("attempt_count") + 1,
+    )
+    if not claimed:
+        return
+
+    row = ConfigNoticeRequest.objects.get(pk=request_id)
+    running = ConfigNoticeRequest.objects.filter(
+        pk=request_id, status=ConfigNoticeRequestStatus.RUNNING
+    )
+    try:
+        if row.kind == KIND_BOARD:
+            _run_board_notice(row)
+        else:
+            _run_surface_notice(row)
+    except Exception:
+        final = row.attempt_count >= MAX_CONFIG_NOTICE_ATTEMPTS
+        logger.log(
+            logging.ERROR if final else logging.WARNING,
+            "config notice %s: emit failed on attempt %d%s",
+            request_id,
+            row.attempt_count,
+            " — abandoned" if final else "; left pending for the drain",
+            exc_info=True,
+        )
+        running.update(
+            status=ConfigNoticeRequestStatus.DEAD if final else ConfigNoticeRequestStatus.PENDING,
+            completed_at=timezone.now() if final else None,
+        )
+        return
+    running.update(status=ConfigNoticeRequestStatus.DONE, completed_at=timezone.now())
+
+
+def _run_board_notice(row: Any) -> None:
+    payload = row.payload
+    project_id = str(payload["project_id"])
+    removed = [_RemovedLane(**lane) for lane in payload["removed"]]
+    hidden = [_HiddenColumn(**column) for column in payload["hidden"]]
+    suppressed = _cooling_down(
+        KIND_BOARD, row.actor_id, str(row.pk), {project_id: _board_signature(removed, hidden)}
+    )
+    if project_id in suppressed:
+        return
+    _emit_board_notifications(project_id, row.actor_id, removed, hidden, str(payload["actor_name"]))
+
+
+def _run_surface_notice(row: Any) -> None:
+    payload = row.payload
+    changes = [_surface_change_from_json(change) for change in payload["changes"]]
+    suppressed = _cooling_down(
+        KIND_SURFACE,
+        row.actor_id,
+        str(row.pk),
+        {change.project_id: _surface_signature(change) for change in changes},
+    )
+    live = [change for change in changes if change.project_id not in suppressed]
+    if live:
+        _emit_surface_notifications(live, row.actor_id, str(payload["actor_name"]))
+
+
+def _board_signature(removed: list[_RemovedLane], hidden: list[_HiddenColumn]) -> str:
+    """What a board notice asserts: which lanes went where, which columns went away."""
+    return json.dumps(
+        {
+            "removed": sorted([lane.key, lane.column_label, lane.destination] for lane in removed),
+            "hidden": sorted(column.status for column in hidden),
+        },
+        sort_keys=True,
+    )
+
+
+def _surface_signature(change: SurfaceChange) -> str:
+    """What a surface notice asserts — the same three facts ``_attribution_clauses`` renders."""
+    before, after = change.before, change.after
+    return json.dumps(
+        {
+            "preset": after.methodology if before.methodology != after.methodology else None,
+            "hidden": sorted(
+                k for k, v in after.visibility.items() if before.visibility.get(k) and not v
+            ),
+            "shown": sorted(
+                k for k, v in after.visibility.items() if v and not before.visibility.get(k, False)
+            ),
+        },
+        sort_keys=True,
+    )
+
+
+def _cooling_down(
+    kind: str, actor_id: Any, request_id: str, signatures: dict[str, str]
+) -> set[str]:
+    """Projects whose notice repeats the last one sent for them, by the same actor.
+
+    Suppresses only when the stored actor, the signature, AND a *different* outbox
+    row all match the last notice recorded for ``(kind, project)``:
+
+    * **Against the last notice sent, never "any recent" one.** After
+      Agile→Waterfall→Agile, a third flip to Waterfall must send — suppressing it
+      because the first matched would leave the recipient's latest notice saying
+      Agile about a project that runs as Waterfall. A hide/un-hide/hide cycle does
+      collapse, because the un-hide sends nothing and the last notice still says
+      "hidden".
+    * **Keyed per project, with the actor stored.** If someone else's notice
+      intervened, the stored actor no longer matches and the repeat sends.
+    * **The row id is stored** so a row the drain re-drives after a worker died
+      mid-emit does not find its own signature and suppress the chunks it never
+      wrote.
+
+    Fails open on a Valkey error, as ``MentionRateThrottle`` does: the cooldown only
+    ever removes noise and must never be the way a notice is lost (ADR-1174 §D).
+    The window is fixed from the notice that was sent, not slid by suppressed
+    repeats, so a change toggled indefinitely still re-notifies once per window.
+    """
+    from typing import cast
+
+    import redis
+    from django.conf import settings
+
+    from trueppm_api.core import valkey
+
+    window = int(getattr(settings, "TRUEPPM_CONFIG_NOTICE_COOLDOWN_SECONDS", 0) or 0)
+    if window <= 0 or actor_id is None or not signatures:
+        return set()
+
+    actor = str(actor_id)
+    items = list(signatures.items())
+    keys = [f"config_notice:last:{kind}:{project_id}" for project_id, _ in items]
+    suppressed: set[str] = set()
+    try:
+        client = valkey.client(valkey.DB_NOTIFICATIONS, decode_responses=True)
+        previous = cast("list[str | None]", client.mget(keys))
+        pipe = client.pipeline(transaction=False)
+        for (project_id, signature), key, stored in zip(items, keys, previous, strict=True):
+            if stored is not None:
+                last_actor, last_signature, last_request = json.loads(stored)
+                if (
+                    last_actor == actor
+                    and last_signature == signature
+                    and last_request != request_id
+                ):
+                    suppressed.add(project_id)
+                    continue
+            pipe.set(key, json.dumps([actor, signature, request_id]), ex=window)
+        pipe.execute()
+    except redis.RedisError:
+        logger.exception("config notice cooldown: Valkey error, failing open")
+        return set()
+
+    for project_id in suppressed:
+        logger.info(
+            "config notice suppressed for project %s: repeats the last %s notice actor %s sent "
+            "within %ss (TRUEPPM_CONFIG_NOTICE_COOLDOWN_SECONDS)",
+            project_id,
+            kind,
+            actor,
+            window,
+        )
+    return suppressed
+
+
+def _emit_surface_notifications(
+    changes: list[SurfaceChange],
+    actor_id: Any,
+    actor_name: str,
+) -> None:
+    """Render and write one notice per recipient across every changed project.
+
+    **Every read is hoisted out of the per-project loop** (#3335). The program
+    settings matrix can hand this up to ``MAX_BULK_TARGETS`` projects in one
+    outbox row. Since #3009 the emit runs in the ``projects.emit_config_notice``
+    worker rather than the request thread, but a read left inside the loop would
+    still be two hundred round-trips holding a worker slot. Each read is
+    ``project_id IN (...)`` grouped by project, and nothing in the batch depends
+    on another project's result.
+
+    The work is then processed in chunks of :data:`SURFACE_EMIT_CHUNK_SIZE`
+    projects rather than as one batch, which is a deliberate trade of a little of
+    that saving for two bounds the flat version did not have — see that constant
+    for why. Within a chunk the cost is flat: the same eight reads whether the
+    chunk holds one project or fifty.
+
+    The per-project ``try`` survives the hoist and now guards **only rendering**,
+    which is where a per-project failure can actually originate: a malformed
+    snapshot in one project's copy must not swallow the notices for the rest of
+    the batch. The per-chunk ``try`` is both the on-commit contract — this
+    callback runs after the write has been accepted and must never raise into it
+    — and the reason a failed read or insert costs one chunk rather than the
+    whole apply.
+    """
+    from django.db.models import Q
+
+    from trueppm_api.apps.notifications.models import NotificationEventType
+    from trueppm_api.apps.notifications.services import (
+        create_event_notifications_multi_project,
+    )
+
+    for chunk in _chunked(changes, SURFACE_EMIT_CHUNK_SIZE):
+        project_ids = [change.project_id for change in chunk]
+        try:
+            recipients_by_project = surface_recipient_ids_by_project(
+                project_ids, exclude_user_id=actor_id
+            )
+            counts_by_project = _counts_by_user_by_project(project_ids, Q())
+
+            rows: list[tuple[Any, Any, str, str, Any]] = []
+            for change in chunk:
+                try:
+                    pid = str(change.project_id)
+                    recipient_ids = recipients_by_project.get(pid, [])
+                    if not recipient_ids:
+                        continue
+                    counts = counts_by_project.get(pid, Counter())
+                    subject = _surface_subject(change.before, change.after)
+                    # Materialized before it is appended, so a render that fails
+                    # half-way through one project's recipients contributes
+                    # nothing rather than a partial fan-out.
+                    rendered = [
+                        (
+                            rid,
+                            change.project_id,
+                            subject,
+                            _surface_body(
+                                actor_name, change.before, change.after, counts.get(rid, 0)
+                            ),
+                            None,
+                        )
+                        for rid in recipient_ids
+                    ]
+                    rows.extend(rendered)
+                except SoftTimeLimitExceeded:
+                    raise
+                except Exception:
+                    logger.exception(
+                        "notify_project_surface_change: render failed for project %s",
+                        change.project_id,
+                    )
+
+            if not rows:
+                continue
+            # ``Notification`` carries project_id per row, so a chunk is one
+            # insert (itself capped at NOTIFICATION_BULK_BATCH_SIZE rows per
+            # statement) rather than one insert per project.
+            create_event_notifications_multi_project(
+                event_type=NotificationEventType.PROJECT_CONFIG_CHANGED,
+                rows=rows,
+            )
+        except SoftTimeLimitExceeded:
+            raise
+        except Exception:
+            logger.exception(
+                "notify_project_surface_change: emit failed for projects %s", project_ids
+            )