Skip to content

feat(email): rules turn inbound mail into owned actions (EA-3) - #637

Open
privatejoel wants to merge 1 commit into
claude/email-ea2-gmailfrom
claude/email-ea3-actions
Open

privatejoel wants to merge 1 commit into
claude/email-ea2-gmailfrom
claude/email-ea3-actions

Conversation

@privatejoel

@privatejoel privatejoel commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

EA-3 of the email accountability plan (#634, sections 6.2 to 6.5). The sync engine turns business-critical inbound mail into owned actions. It uses deterministic rules and no LLM.

Stacked on #636 (EA-2) ← #635 (EA-1) ← #619. Merge them in that order.

  • Migration 252 work_items. This is the WORK_MANAGEMENT_SCOPE.md 4.2 table, decision ED-1. The names and types are the same as in the design, without item_key, the template columns and custom. WM-5 adds those later with add column if not exists. An email action is type 'task' with subject_type 'email_action'. The source_key is unique while the item is open. RLS is on with no policy for tenant users, because the items carry mail subjects.
  • Migration 268:
    • email_actions: the email side of one action. It holds IDs and short metadata only, with no body.
    • email_rules: rules for the tenant, or rules for one user.
    • email_action_ensure(): makes the work item and the email action in one transaction. The key (tenant_id, message_key, action_type) is unique for life. Thus these cases never make a second action: a replayed page, a reset checkpoint, and a second mailbox that got the same message. A second mailbox is recorded in seen_connection_ids. Only the service role can execute the function.
    • tenant_settings.email_actions_mode. The default is observe: the engine writes nothing and counts what create would make. The logistics monitor's first run made about 2,000 wrong rows, and this setting prevents that.
    • tenant_settings.email_content_retention_days, for the EA-8 purge.
  • email-accountability/rules.js is a pure function that has no network and no database. It gives:
    • Exclusions: List-Unsubscribe or Precedence: bulk, Auto-Submitted, out-of-office and bounce subjects, no-reply senders, internal senders, and exclusion rules. A trusted-sender rule lets an internal sender through.
    • A default phrase pack: payment overdue, order confirmation, approval required, document pending, shipment delay, deadline or urgent, escalation or legal notice. Each phrase maps to an action type, a priority and a risk. One message can need up to 3 actions.
    • Facts and inferences apart: a phrase, a known contact, a PO reference and a stated deadline are facts. Priority, review and the policy due time are inferences.
    • When to create: an action is made for a critical or high message. A normal message gets an action only when a known contact asks for something. A critical or high message from a sender the CRM cannot place goes to awaiting_review. It is never ignored and never goes straight into an owner's queue.
    • Due time: a stated deadline gives the close of business that day (due_source 'customer_commit'). The forms are "by 25 Oct", "by tomorrow", "within 3 working days" and "before 05/11/2026". Otherwise the policy gives critical 4, high 8 and normal 16 business hours ('sla'). A deadline rule can override this for one action type.
    • Keyword, customer-floor, deadline, trusted-sender and exclusion rules.
  • link.js: a link is made only when the match is reliable. The cases are: the exact contact address (canonical hash), the exact customer address, a business domain that only one customer uses, and a PO number that appears as a whole token on that customer's open order. A free-mail domain or a shared domain gives a reason and no link. ilike patterns are escaped. The shared matchInboundToCustomer is not used, because it links gmail.com.
  • store.js is the only module that knows an action is a work_items row plus an email_actions row. If ED-1 changes, only this file changes.
  • engine.js is the onPage of the sync:
    • A follow-up in a thread that has an open action of the same type updates that action's activity time and can raise its priority. It makes no new action.
    • The owner is the owner of the mailbox. The backup is the customer's owner. An owner who has left the tenant leaves the action in detected with no owner.
    • When two mailboxes get the same message, the person in To takes an action that nobody has started from the person in Cc. The switch is audited.
    • The engine reads no read state. Outbound mail is left for EA-5.
    • The engine's counts go into last_sync_stats: created, would_create, excluded, irrelevant, follow_ups and reassigned.
    • Synced mail never goes into inbound_emails, so it never reaches the tick's LLM classifier or the draft-order step.

Deploy notes

  1. Merge fix(secrets): own IV per stored credential, no plaintext fallback, https Tally bridge #619, feat(email): connect a user's Outlook mailbox and poll Inbox and Sent (EA-1) #635 and feat(email): connect a Gmail mailbox on the tenant's own Google app (EA-2) #636 first.
  2. Apply migrations 252 and 268 by hand, after 267. Then run notify pgrst, 'reload schema';.
  3. email_actions_mode stays observe. Leave it there until EA-5 (verification) is merged, because without EA-5 no action closes by itself. Before you switch, read last_sync_stats.would_create on the mailboxes. To switch: update tenant_settings set email_actions_mode = 'create' where tenant_id = '<id>';.

Tests

src/v3-app/api-email-rules.test.js (33 tests, pure):

  • Each phrase class maps to the expected type and priority. One message can make several actions.
  • "Urgent" from a known contact is critical. From an unknown sender it is high and goes to review. An escalation from an unknown sender is critical and goes to review.
  • Each exclusion is checked: bulk, Precedence, Auto-Submitted (but no passes), out of office, no-reply, internal, an exclusion rule by domain and by phrase, and a trusted sender that lets an internal sender through.
  • Keyword, customer-floor and deadline rules are checked, and senderMatches matches a domain and its subdomains.
  • Facts and inferences are kept apart in the reasons.
  • Stated deadlines are checked: dates, "tomorrow", "EOD", DMY dates, month-first dates, working days, hours, a date with no year that is past (next year), "31 Feb" (no deadline), and a date with no lead word (no deadline).
  • Business hours skip Saturday and Sunday. Friday 16:00 plus 4 business hours is Monday 12:00. A normal request with a deadline by the end of the next business day becomes high.
  • A follow-up type is left out of the new actions.

src/v3-app/api-email-engine.test.js (21 tests). It uses the memory fake and a stand-in for email_action_ensure with the same semantics:

  • [1] A critical email makes one work item and one email action. The test checks the owner, the backup, the due time, the account, the reasons and the audit row. Review and detected cases are covered too.
  • [2] These make nothing: bulk mail, an internal sender, an unknown sender with no phrase, and a known contact with no request. A connected free-mail mailbox does not make free-mail senders internal. Observe mode writes nothing and counts. Outbound mail makes no action.
  • [3] These stay one action: the same page twice, the same message after a checkpoint reset, and the same message in a second mailbox (both mailboxes are recorded). A To recipient takes an untouched action from a Cc recipient. Work in progress is never taken. A follow-up updates the open action and raises its priority. A closed action does not hide a new request.
  • [4] An exact contact plus a PO number links the customer, the order and the opportunity. These link nothing: a PO number inside a longer number, a PO on a cancelled order, a free-mail sender, and a domain shared by two customers. A domain that one customer uses gets linked. An _ in a domain is not a wildcard.
  • [9] The same message seen again, read or not, leaves the state as it was.
  • [18] Orders, customers and contacts are unchanged, and inbound_emails, communications and quote_approvals stay empty.
  • One end-to-end test: a Graph page passes through runEmailSync and the engine, makes one action, and the mailbox stats count it.

SQL on a real Postgres engine. No Postgres runs on this machine, and stacked PRs get no CI. So I applied supabase/ci-bootstrap.sql and all 233 migrations to PGlite 0.5.8, a WASM Postgres, with pgvector 0.0.9. This is what scripts/db/apply-migrations.sh does in CI. I installed PGlite in a scratch folder, outside the repo. Then I ran these checks on email_action_ensure:

  • The first call creates the pair.
  • The same message from a second mailbox returns the same pair (created = false, seen_connection_ids has 2 entries).
  • A second action type creates a new pair.
  • A message with no Message-ID gets its key from the provider ID, and a second call returns the same pair.
  • In the database: 3 actions and 3 work items. source_key = 'email_action:' || id and subject_id = id.
  • A second open item with the same source_key raises unique_violation.
  • authenticated cannot execute the function, and service_role can.

All checks passed.

Mutation check: I broke each rule, ran the two files and restored the code. 21 of 23 mutations failed the tests. The 2 that survived are equivalent: when a match is not reliable, linkSender returns no customer_id, and a request from an unknown sender is irrelevant either way. The killed mutations:

  • observe mode writes;
  • no follow-up suppression;
  • a free-mail domain links;
  • an unescaped ilike;
  • a shared domain links;
  • a PO number inside a longer number;
  • a cancelled order links;
  • no review for unknown senders;
  • internal, bulk, no-reply and auto-reply mail is not excluded (4 mutations);
  • work in progress is reassigned;
  • the mailbox link moves although the owner did not change;
  • the owner's membership is not checked;
  • outbound mail is processed as inbound;
  • a closed action hides a new request;
  • a follow-up never raises the priority;
  • a stated deadline is ignored;
  • weekends count;
  • a free-mail mailbox domain counts as internal.

Two mutations first survived and showed real gaps, which I fixed:

  • The owner switch is now one conditional update, and the email-action update depends on it.
  • The outbound test now uses an external sender.

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 docs/RBAC_AUDIT.md and docs/WRITE_PATH_AUDIT.md.
  • npm run eval:golden: pass.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 629 files, 7,553 tests, all pass.

Not covered

  • No API and no UI for actions or rules yet. EA-4 and EA-7 add them.
  • No verification of replies or forwards, so no action closes by itself. EA-5 adds this. Keep observe until then.
  • No reminders or escalation. EA-6 adds them.
  • The phrases are English only. Other languages need keyword rules.
  • shortcut: the weekend is Saturday and Sunday, there are no holidays, and the business hours are fixed at 09:30 to 17:30. EA-6 reads these from the policy and from holiday_calendar. Many Indian distributors work on Saturday.
  • shortcut: zonedToUtc uses one offset step, so a time inside a DST change can be one hour off. India has no DST.
  • The default timezone is Asia/Kolkata. Anvil has no tenant timezone column. EA-6 adds it to the policy.
  • PGlite is not the production Postgres. The CI migrations job runs when this stack reaches main.

🤖 Generated with Claude Code

Migration 252 work_items (the WM-5 subset) and 268 email_actions,
email_rules and email_action_ensure (one transaction, unique for life on
tenant, message key and action type). Deterministic rules with facts and
inferences apart, exclusions, stated deadlines and business-hour due
times. Links only on a reliable match: exact contact or customer address,
a business domain one customer uses, a PO number as a whole token. Follow-
ups update the open action. Observe mode is the default and writes
nothing.

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 2:45am UTC

This branch was successfully deployed

1 active deployment
Preview — 87e99f1b 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