Skip to content

feat(email): reminders and escalation on a policy, with no duplicate notice (EA-6) - #640

Open
privatejoel wants to merge 2 commits into
claude/email-ea5-verifyfrom
claude/email-ea6-escalation
Open

privatejoel wants to merge 2 commits into
claude/email-ea5-verifyfrom
claude/email-ea6-escalation

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

EA-6 of the email accountability plan (#634, section 6.7). This PR adds reminders and escalation for open email actions. They run on the existing tick and the daily cron, and they use the bell. Their policy is a setting, not code. A repeated run never sends a notice twice.

Stacked on #639 (EA-5) ← #638 ← #637 ← #636 ← #635 ← #619. This PR also contains the commit of #624 (notify() and migration 253) as a cherry-pick (35b8f28), because the reminders go to one person at a time. When #624 merges into main, a rebase of this stack drops the duplicate commit. Review only the second commit (6182810) here.

  • Migration 270:

    • email_action_notices is the ledger. The sweep sends a notice only after it inserts the ledger row. The key (email_action_id, notice_key) is unique.
    • tenant_settings.email_policy holds the tenant's overlay on the default policy.
  • policy.js:

    • The defaults are in code. The tenant overlay merges key by key (the mergeRules pattern). Overrides apply in order and match by priority, action type or mailbox. For example, confirm_payment can have its own ladder.
    • The keys: timezone; business hours, with the weekend days as a setting (many Indian distributors work on Saturday); the due minutes for each priority; notify_on_create; the acknowledgement time; the due-soon time; the overdue ladder (after_minutes, backup, roles); the roles to tell when an action has no owner; and the cap for each run.
    • policyErrors() checks every key. It refuses an unknown key, a bad time or timezone, an unknown role, a ladder that does not grow, and a weekend with no work day.
    • "Department" is a role here, because Anvil has no department table or manager table (ED-9).
  • The defaults (plan 6.7):

    Priority Notice when made Not started Due soon Overdue ladder
    critical owner after 60 min 120 min before 0 h: owner, backup and sales_manager. 24 h: the same again. 48 h: owner, backup and admin
    high after 240 min 120 min before 0 h: owner and backup. 24 h: owner, backup and sales_manager
    normal 240 min before 0 h: owner

    The not-started and due-soon times are business minutes. The ladder times are calendar time after the due time.

  • escalation.js:

    • noticesFor() is a pure function. It gives the notices that one action is due now.
    • Each key holds the kind, the reopen count, the level, the owner (for notices to the owner) and the due time. A new owner, a new due time or a reopen gives a new key. Nothing else does.
    • When the owner is no longer an approved member, the backup and the policy roles get the notice.
    • Privacy: a notice to the owner names the mail subject. An escalation to the backup or to roles names no subject, because a role may not be allowed to open the action.
    • runSweep() sends the notices through notify() (feat(notifications): a notice per person and a bell for every role, on desktop and phone #624), so each recipient gets their own bell row. A failed send is retried on later sweeps, up to 3 attempts. Each run has a cap, and the rest waits for the next sweep. escalation_level only goes up. Overdue notices and escalations are audited.
  • Where it runs: /api/email/sweep (cron only) is email/sweep in the tick ALWAYS group, and email/sweep_daily in cron/daily.js is the backstop. heartbeat-check.js gives the daily row a 30-hour bound. With the 10-minute default, /api/_healthz would report 503 for most of every day (the logistics lesson).

  • /api/email/policy: any writer can GET the stored, effective and default policy. PUT needs email.rules, is validated, and is audited.

  • The engine and the rules now read the policy. Due times use the tenant's timezone, business hours, weekend and due minutes (by priority and action type). tenant_settings is read whole, so a migration that is not applied yet makes a column read as missing. It does not stop the sync.

No new npm package. No paid service. In-app notices only.

Deploy notes

  1. Merge feat(notifications): a notice per person and a bell for every role, on desktop and phone #624 (or this stack with its copy of feat(notifications): a notice per person and a bell for every role, on desktop and phone #624) and apply migration 253 before you turn on reminders. Without 253, notify() skips the notice. The ledger then marks it failed and retries it up to 3 times.
  2. Apply migration 270 after 269. Then run notify pgrst, 'reload schema';.
  3. The sweep runs only for tenants with email_accountability_enabled and email_actions_mode = 'create'. It needs the 5-minute tick trigger (cron-job.org, fix(cron): give the 5-minute tick a scheduler, behind an allow-list that defaults to extraction jobs only #566 or pg_cron). If fix(cron): give the 5-minute tick a scheduler, behind an allow-list that defaults to extraction jobs only #566 is merged, add email/sweep to CRON_TICK_HANDLERS. The daily backstop runs on Vercel's own cron.
  4. Optional: set the tenant policy with PUT /api/email/policy { policy: { ... } }. For a Saturday work day: { "business_hours": { "weekend": ["Sun"] } }.

Tests

src/v3-app/api-email-escalation.test.js (24 tests):

  • [10] An overdue item escalates per policy:
    • A critical item 2 h overdue: the owner gets the created and overdue notices. The backup and sales_manager get the escalation, at level 1.
    • The ladder climbs: level 2 after 1 day, and admin at level 3 after 2 days.
    • An escalation names no subject. An owner notice does. Each notice links to the action.
    • When the owner has left the tenant, the backup and the roles get the notices.
    • An override by action type sends payment escalations to finance.
    • Performed, cancelled and informational items get nothing. A closed item is due nothing, even when it is overdue.
  • [12] Repeated runs do not duplicate reminders:
    • A second and a third sweep send nothing new, and the ledger keys stay the same.
    • A notice that another sweep claimed first is not sent again.
    • A failed send stops after 3 attempts. A send that recovers is marked sent once.
    • The cap holds the rest for the next sweep.
  • Re-arming:
    • A new owner gets the owner notices, and the escalation is not sent again.
    • A new due time re-arms the ladder (due soon, then overdue).
    • A reopen starts a new cycle.
    • observe mode sends nothing.
  • Business time:
    • The not-started reminder fires once for an action that has not started, and not for work in progress.
    • Its time counts business hours: an action made Friday 17:00 gets the reminder on Monday, not on Saturday.
    • Due soon fires only inside its window.
    • A tenant that works on Saturday counts Saturday.
  • The real notify() from feat(notifications): a notice per person and a bell for every role, on desktop and phone #624: the users and the role members each get their own admin_notifications row (recipient_user_id).
  • Policy:
    • The overlay merges key by key, and an override applies by its match.
    • The validator refuses an unknown key, a bad time, a bad timezone, a bad role, a ladder that does not grow, and a weekend with no work day.
    • GET returns the effective policy. Only an admin can PUT, a bad policy is 400 with its errors, and a good one is saved and audited.

Mutation check: I broke each rule, ran the file and restored the code. All 21 mutations failed the tests. The mutations:

  • the ledger ignored;
  • no retry limit;
  • a failed send never retried;
  • no cap for each run;
  • the owner not in the owner keys;
  • the due time not in the overdue key;
  • a reopen does not re-arm;
  • the escalation names the subject;
  • an owner who left is still told;
  • overrides ignored;
  • the escalation level not recorded;
  • every step fires at once;
  • observe tenants swept;
  • closed items notified;
  • the acknowledgement time in calendar time;
  • the weekend setting ignored;
  • unknown policy keys allowed;
  • any writer sets the policy;
  • a reminder for work in progress;
  • the ladder order not checked;
  • a failed send counted as sent.

One mutation ("closed items notified") first survived, because the sweep's query also filters closed items. I added a direct test of the pure function.

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors. The new files add no warnings.
  • npm run build: pass.
  • npm run verify: pass. I restored the unrelated rewrites of the audit docs.
  • npm run eval:golden: pass.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 637 files, 7,661 tests, all pass. This count includes the feat(notifications): a notice per person and a bell for every role, on desktop and phone #624 tests.
  • PGlite 0.5.8: all 236 migrations apply, including 253 and 270.

Not covered

  • No email channel and no push for reminders. Only the bell is used. sendEmail could add email later, behind a policy key.
  • shortcut: no holidays. business-time.js can read holiday_calendar when a tenant needs it.
  • shortcut: a ledger row that stays in claimed (the process died between the claim and the send) is never sent again. This is safe against duplicates, but a notice can be lost.
  • shortcut: no digest. The cap (25 by default) holds the rest for the next sweep.
  • Anvil has no leave or availability model, so "owner unavailable" means "the owner is no longer an approved member".
  • No UI for the policy. EA-7 and EA-8 add one.

🤖 Generated with Claude Code

privatejoel and others added 2 commits October 23, 2026 08:41
…n desktop and phone

C-17 (WM-7, R-F5). Migration 253 adds admin_notifications.recipient_user_id.
A null value is a broadcast row, as before. A user id is a row for that
person only.

- notify(svc, tenantId, payload, { users, roles, dedupKey }) writes one row
  per recipient. A role expands to the approved members of this tenant.
- notifyAdmins does not change. It writes one broadcast row.
- GET /api/admin/notifications shows the caller their own rows. Admin and
  operator also see the broadcast rows, as before.
- mark_read and mark_all_read are open to every role. They touch only the
  rows that the caller sees. Resolve stays admin only.
- The bell shows for every role in Shell and in MobileShell.
- Before migration 253 is applied, notify skips and logs. It does not write
  a broadcast row. The list shows nothing to a role that is not admin or
  operator.
- The header comment in notifications.js said one row per recipient. That
  was false. It is correct now.

No new events. C-19 adds them.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…notice (EA-6)

Migration 270 email_action_notices (the ledger, unique per action and
key) and tenant_settings.email_policy. Defaults in policy.js, a tenant
overlay and overrides by priority, action type and mailbox; validated by
PUT /api/email/policy (email.rules). The sweep sends a created notice, an
acknowledgement reminder, a due-soon reminder and an overdue ladder to the
owner, the backup and roles, through notify() of #624. A new owner, a new
due time or a reopen re-arms; nothing else does. Failed sends retry up to 3
times. Business hours, timezone and the weekend follow the policy.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 23, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 23, 2026 3:22am UTC

This branch was successfully deployed

1 active deployment
Preview — 61828102 Deployed Oct 23, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant