velocity-python 0.2.3__tar.gz → 0.2.4__tar.gz

{velocity_python-0.2.3/src/velocity_python.egg-info → velocity_python-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.3
+Version: 0.2.4
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.2.3 → velocity_python-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.2.3"
+version = "0.2.4"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.3"
+__version__ = version = "0.2.4"
 
 import importlib as _importlib
 

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/context.py

@@ -1093,6 +1093,9 @@ class Context:
                 "enabled": response.get("Enabled"),
                 "user_status": response.get("UserStatus"),
                 "sub": attributes.get("sub", user_sub),
+                # the token issuer for this pool: with "sub", the identity
+                # the provider never reassigns (velocity.aws.identity)
+                "issuer": f"https://{user_pool_segment}",
             }
 
             return user

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/lambda_handler.py

@@ -177,10 +177,15 @@ class LambdaHandler(BaseHandler):
                 )
 
             context.perf.start("user lookup")
-            user = self._cached_user(tx, session.get("email_address"))
+            user = self._find_current_user(tx, session, masquerade)
             context.perf.log("user lookup")
             if not user and not masquerade and _stage_allows_provisioning():
-                user = self._provision_and_reload(tx, session)
+                if self._by_subject(masquerade):
+                    # the hook's new row is bound on this, its first, sign-in
+                    self.provision_missing_user(tx, session)
+                    user = self._find_current_user(tx, session, masquerade)
+                else:
+                    user = self._provision_and_reload(tx, session)
             if not user:
                 raise UserNotProvisionedError(
                     "A valid user with permission is required to access this function [DB]"
@@ -245,6 +250,59 @@ class LambdaHandler(BaseHandler):
             )
         return user
 
+    # How a request finds its user row (velocity.aws.identity): "email" (the
+    # default) or "subject" — the identity provider's issuer + subject, the
+    # row bound once by verified email on the first sign-in after the switch.
+    # The IdentityMode config key (per environment) overrides this.
+    identity_mode = "email"
+
+    def _by_subject(self, masquerade):
+        from velocity.aws import identity
+
+        # a masquerade identity is the grant's user, not a provider subject;
+        # the mode is the IdentityMode config key, else identity_mode
+        return not masquerade and identity.mode_of(self) == identity.IDENTITY_SUBJECT
+
+    def _find_current_user(self, tx, session, masquerade=False):
+        """The signed-in caller's user row (dict) or None, by email or — in
+        ``identity_mode = "subject"`` — by issuer + subject."""
+        if not self._by_subject(masquerade):
+            return self._cached_user(tx, session.get("email_address"))
+        from velocity.aws import identity
+
+        issuer, subject, email, verified = identity.claims_of(self.cognito_user)
+        session["iss"], session["sub"] = issuer, subject
+        if not (issuer and subject):
+            return None
+        return self._cached_subject_user(tx, issuer, subject, email, verified)
+
+    def _cached_subject_user(self, tx, issuer, subject, email, verified):
+        """``_cached_user`` by issuer + subject. A first sign-in binds its row
+        inside the load; a miss is never cached."""
+        from velocity.cache import memo
+
+        from velocity.aws import identity
+        from velocity.aws.handlers.context import user_cache_seconds
+
+        def load():
+            return identity.find_user(
+                tx, self.user_table, issuer, subject, email, verified
+            )
+
+        key = ("user-subject", self.user_table, issuer, subject)
+        if getattr(self, "permission_source", None) == "tables":
+            from velocity.aws import permissions as _grants
+
+            key = (*key, _grants.cached_version(tx))
+        user = memo(
+            key,
+            load,
+            user_cache_seconds(),
+            tables=(self.user_table,),
+            cache_none=False,
+        )
+        return dict(user) if user else None
+
     def _cached_user(self, tx, email_address):
         """The user-table row for the signed-in user as a dict, through the
         process read cache (velocity.cache) for ``UserCacheSeconds``: one

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/mixins/__init__.py

@@ -23,8 +23,9 @@ from .row_scoped import RowScopedDataService
 from .audit_trail import AuditTrailMixin
 from .job_handler import JobHandler
 from .session_control import SessionControlMixin
-from .permissions_actions import PermissionsMixin
-from .tiles_actions import TilesMixin
+from .action_names import action_names
+from .permissions_actions import PERMISSION_ACTIONS, PermissionsMixin
+from .tiles_actions import TILE_ACTIONS, TilesMixin
 from .client_errors import ClientErrorReporting, AnonymousClientErrorReporting
 
 __all__ = [
@@ -37,7 +38,10 @@ __all__ = [
     "JobHandler",
     "SessionControlMixin",
     "PermissionsMixin",
+    "PERMISSION_ACTIONS",
     "TilesMixin",
+    "TILE_ACTIONS",
+    "action_names",
     "ClientErrorReporting",
     "AnonymousClientErrorReporting",
 ]

velocity_python-0.2.4/src/velocity/aws/handlers/mixins/action_names.py

@@ -0,0 +1,30 @@
+"""The client action names a handler class serves, from its methods.
+
+``BaseHandler.format_action_name`` turns ``"tiles-load"`` into
+``"OnActionTilesLoad"``; this is the inverse, for a site's ``client_actions``
+allow-list: ``client_actions = MINE | TILE_ACTIONS | PERMISSION_ACTIONS``
+picks up every action a mixin gains with a release, instead of a list each
+site copies by hand (and forgets to extend: admin refused every tile action
+until its list was edited, 2026-10-14).
+"""
+
+from __future__ import annotations
+
+import re
+
+_PREFIX = "OnAction"
+_WORD = re.compile(r"[A-Z][a-z0-9]*")
+
+
+def action_names(cls) -> frozenset:
+    """The kebab-case action of every ``OnAction<Name>`` method ``cls``
+    itself defines (not inherited ones; not ``OnActionDefault``)."""
+    names = set()
+    for attr, value in vars(cls).items():
+        if not attr.startswith(_PREFIX) or not callable(value):
+            continue
+        rest = attr[len(_PREFIX) :]
+        if not rest or rest == "Default":
+            continue
+        names.add("-".join(word.lower() for word in _WORD.findall(rest)))
+    return frozenset(names)

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/mixins/data_service.py

@@ -426,6 +426,19 @@ def plan_row_number(params):
 
 # result_formats query answers with a file download (velocity.misc.export).
 FILE_EXPORT_FORMATS = frozenset(export.EXPORT_FORMATS)
+# Formats written as XLSX cells, which carry no time zone: aware values are
+# converted to the handler's display_timezone() first.
+XLSX_EXPORT_FORMATS = frozenset({"excel", "xlsx"})
+
+
+def _export_zone(handler, result_format, context):
+    """The display zone for an export: the handler's ``display_timezone``
+    for the XLSX formats, ``None`` for the text formats (which write values
+    as given and need no SSM read)."""
+    if result_format not in XLSX_EXPORT_FORMATS:
+        return None
+    zone_for = getattr(handler, "display_timezone", None)
+    return zone_for(context) if zone_for is not None else None
 
 
 def _positive_int(value):
@@ -679,7 +692,11 @@ class ExportStream:
         """The whole export as one file: :func:`velocity.misc.export.build_buffer`
         over :meth:`rows` (line formats are written as the batches arrive)."""
         built = export.build_buffer(
-            result_format, self.headers, self.rows(), filename_base
+            result_format,
+            self.headers,
+            self.rows(),
+            filename_base,
+            display_timezone=_export_zone(self.handler, result_format, self.context),
         )
         if built is None:
             raise BadRequestError(f"Unsupported export format: {result_format!r}")
@@ -838,6 +855,24 @@ class DataServiceMixin:
         "timestamp": "string",
     }
 
+    def display_timezone(self, context=None):
+        """The zone XLSX exports show times in: Excel cells carry no zone,
+        so an aware value (every ``timestamptz``) is written as its wall time
+        here. Default: the site's ``SiteTimezone`` config key (an IANA name
+        such as ``America/Denver``, read through ``ssm_config.getenv``, which
+        caches it per process); UTC, with a warning, when it is unset or not
+        a zone. Override to choose per request (``context`` is the request
+        context) or per handler. Returns a ``tzinfo``."""
+        try:
+            name = ssm_config.getenv("SiteTimezone", None)
+        except Exception:
+            logger.warning("SiteTimezone could not be read; exports use UTC")
+            name = None
+        if not name:
+            logger.warning("SiteTimezone is not set; exports show times in UTC")
+            return datetime.timezone.utc
+        return export.resolve_display_timezone(name)
+
     def _resolve_query_max_rows(self):
         """Effective query row ceiling: `QueryMaxRows` config key first, then
         the class attribute. Returns a positive int or None (no cap)."""
@@ -2231,6 +2266,7 @@ class DataServiceMixin:
                 data.get("headers", []),
                 data.get("rows", []),
                 filename_base,
+                display_timezone=_export_zone(self, result_format, context),
             )
             if result_format == "excel":
                 # the legacy excel download keeps its caller-chosen filename
@@ -2412,7 +2448,12 @@ class DataServiceMixin:
             )
             rows = result.as_list().all()
             filebuffer = BytesIO()
-            export.create_spreadsheet(headers, rows, filebuffer)
+            export.create_spreadsheet(
+                headers,
+                rows,
+                filebuffer,
+                display_timezone=self.display_timezone(context),
+            )
             context.response().file_download(
                 {
                     "filename": payload.get("filename", "temp_file.xls"),

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/mixins/permissions_actions.py

@@ -63,6 +63,7 @@ from types import SimpleNamespace
 
 from velocity.aws import authz, permissions
 from velocity.aws.handlers.exceptions import AlertError
+from .action_names import action_names
 
 READ = "permissions.read"
 READ_ACTION = "permissions.read"
@@ -804,3 +805,8 @@ class PermissionsMixin:
             )
         )
         context.response().set_body(self._inbox_body(tx, actor))
+
+
+# every action PermissionsMixin serves, for a site's ``client_actions``:
+# ``client_actions = MINE | PERMISSION_ACTIONS``
+PERMISSION_ACTIONS = action_names(PermissionsMixin)

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/mixins/tiles_actions.py

@@ -39,6 +39,7 @@ from velocity.aws import authz, facets, permissions, tiles
 from velocity.aws.handlers.exceptions import AccessError, AlertError
 from velocity.db.fragments import Expr
 from velocity.db.servers.tablehelper import TableHelper
+from .action_names import action_names
 
 logger = logging.getLogger(__name__)
 
@@ -659,3 +660,8 @@ class TilesMixin:
             )
         )
         context.response().set_body(self._manage_body(tx, actor))
+
+
+# every action TilesMixin serves, for a site's ``client_actions``:
+# ``client_actions = MINE | TILE_ACTIONS``
+TILE_ACTIONS = action_names(TilesMixin)

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/handlers/mixins/web_handler.py

@@ -621,6 +621,14 @@ Request Details:
             return
         session = context.session() or {}
         email = session.get("email_address")
+        if not email:
+            # Nobody is signed in (a public page that saves its layout as it
+            # goes): there is no owner, so nothing is saved. Rows mode used to
+            # upsert under a blank userid — one shared junk row per key that
+            # every anonymous visitor overwrote. Not an error, so a public
+            # page does not report a failure on every change.
+            context.response().set_body({"saved": False, "reason": "signed_out"})
+            return
         if self.user_data_mode == USER_DATA_DOCUMENT:
             owner = (getattr(self, "current_user", None) or {}).get("sys_id")
             decision = authz.decide(

velocity_python-0.2.4/src/velocity/aws/identity.py

@@ -0,0 +1,138 @@
+"""Who is signed in: the user row bound to the identity provider's issuer and
+subject, never found by email.
+
+An email address can change, be reused, or be claimed by an external identity
+provider; the provider's issuer plus subject (``iss`` + ``sub``) is the one
+pair it guarantees never to reassign (OpenID Connect Core 1.0, section 5.7).
+So a user row carries the pair it is bound to, and each request finds its
+user by that pair.
+
+The mode is the ``IdentityMode`` config key (SSM ``/{Project}/{env}/`` then
+``/Global/{env}/``) when set, else the handler's ``identity_mode``
+(see ``LambdaHandler.beforeAction``), else ``"email"`` — so a site switches
+one environment at a time, demo first, with no code change:
+
+* ``"email"`` — the default and the behaviour before this module: the user
+  row is found by ``email_address``.
+* ``"subject"`` — the user row is found by :data:`ISSUER_COLUMN` +
+  :data:`SUBJECT_COLUMN`. The first sign-in after a site switches binds its
+  existing row ONCE, by the caller's *verified* email, and only a row not
+  yet bound to anyone; from then on email is never used to find that user.
+  A row already bound to another identity is never re-bound by email (the
+  address moved to a different account), and an unverified email binds
+  nothing.
+
+Both columns are TEXT on the site's user table. Declare them in the site's
+schema lane before switching a locked environment
+(``SCHEMA_COLUMNS``); in an unlocked one the first binding creates them.
+
+A masquerade session keeps the email path: its identity is the verified
+grant's user, not a provider subject.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from velocity.aws import ssm_config
+
+logger = logging.getLogger(__name__)
+
+IDENTITY_EMAIL = "email"
+IDENTITY_SUBJECT = "subject"
+IDENTITY_MODES = (IDENTITY_EMAIL, IDENTITY_SUBJECT)
+
+ISSUER_COLUMN = "identity_issuer"
+SUBJECT_COLUMN = "identity_subject"
+# for a site's schema lane: ensure_columns(tx, user_table, SCHEMA_COLUMNS)
+SCHEMA_COLUMNS = {ISSUER_COLUMN: "TEXT", SUBJECT_COLUMN: "TEXT"}
+
+
+def mode_of(handler):
+    """``IdentityMode`` config first, then the handler's ``identity_mode``,
+    then ``"email"``. A value that is not a mode is ``"email"`` (logged):
+    unlike authorization, the safe fallback is the established lookup, so a
+    typo never locks every user out."""
+    raw = None
+    try:
+        raw = ssm_config.getenv("IdentityMode", None)
+    except Exception:
+        raw = None
+    raw = str(raw or getattr(handler, "identity_mode", None) or IDENTITY_EMAIL)
+    mode = raw.strip().lower()
+    if mode not in IDENTITY_MODES:
+        logger.warning("identity: unknown IdentityMode %r; using email", raw)
+        return IDENTITY_EMAIL
+    return mode
+
+
+def claims_of(cognito_user):
+    """``(issuer, subject, email, email_verified)`` from a resolved Cognito
+    user (``Context.get_cognito_user``); ``None`` parts when absent."""
+    user = cognito_user if isinstance(cognito_user, dict) else {}
+    attributes = user.get("attributes") or {}
+    email = (attributes.get("email") or user.get("email") or "").strip().lower() or None
+    verified = str(attributes.get("email_verified", "")).strip().lower() == "true"
+    return user.get("issuer") or None, user.get("sub") or None, email, verified
+
+
+def _row(found):
+    if not found:
+        return None
+    return found.to_dict() if hasattr(found, "to_dict") else dict(found)
+
+
+def find_bound(tx, user_table, issuer, subject):
+    """The user row bound to ``issuer`` + ``subject``, or None."""
+    if not (issuer and subject):
+        return None
+    return _row(
+        tx.table(user_table).find({ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject})
+    )
+
+
+def bind_by_verified_email(tx, user_table, issuer, subject, email, verified):
+    """Bind the unbound row with this verified email to ``issuer`` +
+    ``subject`` and return it; None when there is nothing it may bind.
+
+    Refuses (returns None, logs why) when the email is not verified, when no
+    row has it, or when that row is already bound to a different identity —
+    the address now belongs to another account, and following it would hand
+    that account someone else's row.
+    """
+    if not (issuer and subject and email):
+        return None
+    if not verified:
+        logger.warning("identity: not binding %s — email not verified", email)
+        return None
+    row = _row(tx.table(user_table).find({"email_address": email}))
+    if not row:
+        return None
+    bound = (row.get(ISSUER_COLUMN), row.get(SUBJECT_COLUMN))
+    if any(bound):
+        if bound != (issuer, subject):
+            logger.warning(
+                "identity: %s row %s is bound to another identity; not re-binding by email",
+                user_table,
+                row.get("sys_id"),
+            )
+            return None
+        return row
+    tx.table(user_table).update(
+        {ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject}, {"sys_id": row["sys_id"]}
+    )
+    logger.info(
+        "identity: bound %s row %s to its sign-in (first sign-in by subject)",
+        user_table,
+        row.get("sys_id"),
+    )
+    row.update({ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject})
+    return row
+
+
+def find_user(tx, user_table, issuer, subject, email=None, verified=False):
+    """The signed-in caller's user row: by ``issuer`` + ``subject``, else (on
+    the first sign-in after the switch) the row its verified email binds."""
+    return find_bound(tx, user_table, issuer, subject) or bind_by_verified_email(
+        tx, user_table, issuer, subject, email, verified
+    )

{velocity_python-0.2.3 → velocity_python-0.2.4}/src/velocity/aws/permissions.py

@@ -13,6 +13,8 @@ holds. This module is where those come from once a site keeps them as data
 ``sys_permission``        the catalog (:func:`velocity.aws.authz.catalog`),
                           materialised so it is a table like any other
 ``sys_authz_state``       one counter, bumped by every change
+``sys_permission_notice`` when each person was last told about waiting
+                          requests (:func:`waiting_notices`)
 
 **The rule.** Start with nothing. Add every *allow* from the user's current
 roles and direct grants. Remove everything matched by any *deny* — a deny
@@ -75,6 +77,7 @@ USER_ROLE_TABLE = "sys_user_role"
 USER_PERMISSION_TABLE = "sys_user_permission"
 REQUEST_TABLE = "sys_permission_request"
 STATE_TABLE = "sys_authz_state"
+NOTICE_TABLE = "sys_permission_notice"
 
 # The column on the site's user table that carries the compiled set.
 USER_COLUMN = "permissions"
@@ -188,6 +191,23 @@ SCHEMA = {
             {"columns": ["status"], "name": "idx__sys_permission_request__status"},
         ],
     },
+    # when a person was last told about something (waiting_notices): one row
+    # per person and kind of notice, so "at most once a day" survives restarts
+    NOTICE_TABLE: {
+        "columns": {
+            "user_sys_id": "BIGINT",
+            "notice": "TEXT",
+            "sent_at": "TIMESTAMPTZ",
+            "sent_to": "TEXT",
+            "waiting": "INTEGER",
+        },
+        "unique_indexes": [
+            {
+                "columns": ["user_sys_id", "notice"],
+                "name": "idx__sys_permission_notice__user_notice",
+            }
+        ],
+    },
 }
 
 GRANT_TABLES = (
@@ -203,7 +223,7 @@ GRANT_TABLES = (
 # (``DataServiceMixin``): a row written around the guards would be a grant
 # nobody was allowed to give.
 PROTECTED_TABLES = frozenset(
-    {STATE_TABLE, PERMISSION_TABLE, REQUEST_TABLE, *GRANT_TABLES}
+    {STATE_TABLE, PERMISSION_TABLE, REQUEST_TABLE, NOTICE_TABLE, *GRANT_TABLES}
 )
 authz.protect_tables(*PROTECTED_TABLES)
 
@@ -1801,3 +1821,171 @@ def requests(tx, *, status=None, user_sys_id=None) -> list:
     table = tx.table(REQUEST_TABLE)
     rows = _rows(table.select(where=where) if where else table.select())
     return sorted(rows, key=lambda row: row["sys_id"], reverse=True)
+
+
+# ── telling the people who decide ──────────────────────────────────────────
+
+# the kind of notice (sys_permission_notice.notice) for requests waiting
+REQUESTS_WAITING = "requests_waiting"
+# nobody is told about waiting requests more often than this
+NOTICE_INTERVAL = datetime.timedelta(days=1)
+DEFAULT_LABEL_COLUMNS = ("full_name", "email_address")
+
+
+@dataclass(frozen=True)
+class WaitingNotice:
+    """One person to tell that requests wait for them (:func:`waiting_notices`).
+
+    ``requests`` holds, oldest first, only what a notice may say: who asked
+    (``person``), what for (``asked_for``: the role's name or the
+    permission's label), where (``scope_type`` / ``scope_id``), and when
+    (``requested_at``). Never the reason."""
+
+    user_sys_id: Any
+    email: str
+    name: str
+    count: int
+    oldest_at: Optional[datetime.datetime]
+    requests: tuple
+    notice: str = REQUESTS_WAITING
+
+
+def _person_label(row, columns):
+    for column in columns:
+        value = str((row or {}).get(column) or "").strip()
+        if value:
+            return value
+    return f"User {(row or {}).get('sys_id')}"
+
+
+def _principal_of_row(row, principal_permissions=None):
+    """The principal a request by this user would have (the same rule as
+    :func:`velocity.aws.authz.principal_for`), never in a masquerade: a
+    notice goes to the person themselves."""
+    from types import SimpleNamespace
+
+    return authz.principal_for(
+        SimpleNamespace(
+            current_user=row,
+            principal_permissions=principal_permissions,
+            permission_source=TABLES,
+            context=None,
+        )
+    )
+
+
+def waiting_notices(
+    tx,
+    user_table,
+    *,
+    email_column="email_address",
+    label_columns=DEFAULT_LABEL_COLUMNS,
+    include=None,
+    principal_permissions=None,
+    every=NOTICE_INTERVAL,
+    now=None,
+) -> list:
+    """Who must be told that access requests are waiting, and what: one
+    :class:`WaitingNotice` per person due one. Reads only; record each
+    notice sent with :func:`record_notice`.
+
+    A person is told when they hold :data:`GRANT` the way deciding needs it
+    (site-wide, or as a super user), at least one pending request is theirs
+    to decide (not their own, a super user excepted, as
+    :func:`decide_request` has it), they have an address in
+    ``email_column``, ``include(row)`` (when given) says yes, and they were
+    not told within ``every``. ``principal_permissions`` is the handler hook
+    of the same name, for permissions a site's code hands out.
+
+    Nothing when the tables are not turned on or nothing waits. Nothing,
+    with a warning, when :data:`NOTICE_TABLE` is missing: without it nobody
+    could be told only once."""
+    if not tables_present(tx):
+        return []
+    # oldest first
+    pending = list(reversed(requests(tx, status=PENDING)))
+    if not pending:
+        return []
+    notices = tx.table(NOTICE_TABLE)
+    if not notices.exists():
+        logger.warning(
+            "permissions: %s is missing; nobody is told about waiting requests "
+            "until the schema step creates it",
+            NOTICE_TABLE,
+        )
+        return []
+    now = _now(now)
+    last = {
+        row.get("user_sys_id"): _aware(row.get("sent_at"))
+        for row in _rows(notices.select(where={"notice": REQUESTS_WAITING}))
+    }
+    people = {row.get("sys_id"): row for row in _rows(tx.table(user_table).select())}
+    roles = {
+        row["sys_id"]: row.get("name") for row in _rows(tx.table(ROLE_TABLE).select())
+    }
+    described = [
+        {
+            "sys_id": row["sys_id"],
+            "user_sys_id": row.get("user_sys_id"),
+            "person": _person_label(
+                people.get(row.get("user_sys_id"))
+                or {"sys_id": row.get("user_sys_id")},
+                label_columns,
+            ),
+            "asked_for": (
+                (roles.get(row.get("role_sys_id")) or f"Role {row.get('role_sys_id')}")
+                if row.get("role_sys_id")
+                else _label(row.get("permission"))
+            ),
+            "scope_type": row.get("scope_type"),
+            "scope_id": row.get("scope_id"),
+            "requested_at": _aware(row.get("requested_at")),
+        }
+        for row in pending
+    ]
+    due = []
+    for user_sys_id, row in sorted(people.items(), key=lambda item: str(item[0])):
+        principal = _principal_of_row(row, principal_permissions)
+        if principal.user_sys_id is None or not principal.holds(GRANT):
+            continue
+        email = str(row.get(email_column) or "").strip()
+        if not email or (include is not None and not include(row)):
+            continue
+        sent_at = last.get(principal.user_sys_id)
+        if sent_at is not None and sent_at > now - every:
+            continue
+        theirs = tuple(
+            entry
+            for entry in described
+            if principal.superuser or entry["user_sys_id"] != principal.user_sys_id
+        )
+        if not theirs:
+            continue
+        times = [e["requested_at"] for e in theirs if e["requested_at"] is not None]
+        due.append(
+            WaitingNotice(
+                user_sys_id=principal.user_sys_id,
+                email=email,
+                name=_person_label(row, label_columns),
+                count=len(theirs),
+                oldest_at=min(times) if times else None,
+                requests=theirs,
+            )
+        )
+    return due
+
+
+def record_notice(tx, notice, *, now=None):
+    """Record that ``notice`` (a :class:`WaitingNotice`) was sent, so the
+    person is not told again within the interval. Call it in the
+    transaction, in the same savepoint as the send."""
+    tx.table(NOTICE_TABLE).merge(
+        {
+            "user_sys_id": notice.user_sys_id,
+            "notice": notice.notice,
+            "sent_at": _now(now),
+            "sent_to": notice.email,
+            "waiting": notice.count,
+        },
+        pk={"user_sys_id": notice.user_sys_id, "notice": notice.notice},
+    )