Pay-As-You-Go Alerts: Every Message Metered

Status: Phases 0–3 are built and deploying to production on 29 September 2026 for final testing. That makes them built, not shipped: shipping is a separate call made after testing. Negative-news alerts ship switched off behind a kill switch until operations turns them on.

Not built: MAUI push notifications (the design made them conditional on everything before them being done), the ML-health-flip event (the grade cache holds no per-symbol ML output to detect a flip in), and the holdings-vs-regime tripwire (deferred). Alerts replaced two earlier roadmap waves: Wave 12 (price & technical alerts) and Wave 22 (tracked-symbol watch). Both are now event types in this one system.

The System in One Paragraph

Every alert is a metered message. Each email or text sent on a user's behalf is recorded in a delivery ledger with our cost and their price. Each day's paid deliveries roll up into one Notification charge per account, which the existing monthly billing engine invoices unchanged, so there's no new payment flow. A small free catalogue (grade changes on tracked symbols, macro regime and grade changes, a weekly digest) is on for every account by default, with one-click unsubscribe. Everything else is opt-in per event, per scope and per channel, behind a "charges apply" consent screen that shows the price list, a live monthly estimate from the user's own lists, and a monthly spend cap ($5 by default) the system can't exceed, even when several detectors fire at the same moment.

The Cap Is One Conditional UPDATE

A spend cap is a promise: "you'll never pay more than $5 this month." The obvious implementation, read the month-to-date total, compare, then insert, breaks under concurrency. The earnings job, the end-of-day price job and the news detector can all admit deliveries for the same account in the same second, and each would read the same total and conclude there's room.

The build keeps a running counter on the account's settings row (SpendMonth, MtdSpend) and makes the check and the increment a single statement:

UPDATE alertsettings
   SET MtdSpend   = (CASE WHEN SpendMonth = @month THEN MtdSpend ELSE 0 END) + @price,
       SpendMonth = @month
 WHERE AccountID = @account AND PaidEnabled = 1
   AND (CASE WHEN SpendMonth = @month THEN MtdSpend ELSE 0 END) + @price <= MonthlyCapAmount

One row affected means admitted; zero means CapBlocked. The month rollover is folded into the same statement, so there's no midnight reset job to race against. The update runs in the same transaction as the ledger insert and the outbound EmailToSend / SmsToSend row, so what's billed and what's queued can't diverge. A duplicate delivery (the ledger is unique per account, event and channel) rolls the whole transaction back, counter included. Messages later suppressed or failed refund the counter and are never billed.

Caveat: the unit test runs against SQLite, not MySQL. The guarantee comes from single-statement atomicity of a conditional UPDATE, which both engines provide (InnoDB takes a row lock for it), not from anything SQLite-specific. Free alerts never touch the counter and are never blocked. Users get a free notice at 80% and 100% of their cap.

The Decisions Worth Defending

The Formula-Change Trap, and Why the Regrade Didn't Cause an Alert Storm

Grade-change alerts are the one alert only GMI can send: "the A we gave this company in June is now a B, and here's the factor that moved." They also had a failure mode that would have fired in the same deploy. Wave 19 moved the grade formula from 1.0 to 1.1 by neutralizing two factors for financial companies, and it shipped to production alongside Alerts. Under a naive design, every user following a bank would have been emailed that day about a change in GMI's formula, not in the company.

Two rules in the build prevent that:

• Formula-version guard. gmi-seopagebuilder writes a publictickergradehistory row (stamped with AiGradeFormulaVersion) only when a ticker's grade, score, factors or formula version changes. Two consecutive rows with different versions produce no company alerts, and one announcement per version pair ("We updated how GMI grades are calculated, formula 1.0 to 1.1"), deduplicated by a key like formula:1.0->1.1.
• First row is a baseline. A symbol's first history row never alerts, because there's nothing to compare it with. The history table is new, so on first deploy every ticker's first row is a baseline, whichever formula version it carries.

Together they mean the regrade and the alerts system could ship in the same week in either order: if the history starts at 1.1, there's nothing to compare; if a 1.0 row exists, the version guard suppresses the move. Detecting what changed had to take into account that GMI changes too.

Phase 0: The Compliance Gaps Found Before Building

Before designing a single paid alert, the design surveyed the email and SMS paths GMI already had. The survey found four gaps, and the build found a fifth. Two of them were a present-day risk, because job notifications already texted numbers that had never been verified. So Phase 0 shipped first, and it was worth doing even if alerts had never launched:

Senders now also record the provider message id (SendGrid X-Message-Id, Twilio SID), so each ledger row's estimated cost can later be reconciled with what the provider actually charged. The consent record (accepted text, price list, the estimate shown, cap, timestamp, IP, terms version) is append-only and serves as both the billing authorization and the SMS-consent evidence.

Pricing: An Ambiguity Resolved, and the Honest Economics

The brief said the price should give "about 80% profit". The platform's existing Claude billing uses an 80% markup (cost × 1.8, about a 44% margin); read literally, 80% profit is an 80% margin (cost × 5). Per-message prices differ by nearly 3× between the two readings, so the design showed both columns and asked instead of guessing. The decision was margin:

The economics, stated plainly: a typical engaged user lands around $1–3 a month, and almost all of it is SMS, because email costs close to nothing to send. The free catalogue costs GMI under a cent per free user per month. It's a retention and trust feature that pays for itself, not a big revenue line. The existing rule that waives invoices under the $0.50 Stripe minimum means a light alerts-only user effectively pays nothing; that's accepted and noted rather than hidden. Paid alerts need a card on file and the consent screen, and adding a card makes the account Paid tier, which is the existing model.

Negative News: Precision First, and Shipped Off

This is the only alert that needed new intelligence, and the one most likely to embarrass the product. The design principle: one absurd alert costs more trust than ten misses. So the classifier is built for precision:

• A lexicon pass decides the clear cases using whole-word matches, with guards for figurative use ("plunges into a new market") and market-roundup headlines ("5 stocks to watch", "Nasdaq falls"), which aren't news about one company. A headline is clearly negative only when it has several strong negative terms, nothing positive, and names the company.
• Only the ambiguous middle goes to Claude Haiku, with a strict prompt ("bad news about this company") and a JSON verdict. An alert fires only when the article is negative and about the company and confidence is at least 0.85.
• Bounded cost. It reads only newly cached articles (under 2 days old) for symbols that paid accounts follow for news. There's a per-cycle cap on Claude calls: when it's spent, the detector stops without advancing its watermark, so the next article is judged next cycle instead of skipped. The first run sets a baseline and never alerts on history. The $0.005 surcharge applies only to alerts Claude actually adjudicated.
• Ships kill-switched. Users can select it, but it stays off until someone reviews real verdicts and turns it on from the admin Alerts Operations page. The threshold starts high and gets tuned down later, not the other way round.

What Each Phase Built

106 unit tests cover the spine, compliance, the paid detectors and the classifier, including a test that fails on "should", "consider", "recommend", "buy now" or "sell now" in any alert template. Every template follows the platform's voice rule: "AAPL moved from A− to B+; the largest factor change was debt-to-equity", never "consider selling". The build added 17 HTTP endpoints, none under the Functions host's reserved admin/ prefix.