# Phase 16 — Telegram Notifications and Reminders Report

## Status

Phase 16 is complete. The project now has dynamic versioned bot templates, a transactional MySQL outbox, leased/retry-safe Telegram workers, timezone-aware reminder schedules, two-person broadcast approval, bounded audience materialization, delivery reporting, and an authenticated Mini App notification inbox.

## Delivered

- Migration `021_harden_notification_delivery.sql` adds immutable template revisions and message-attempt evidence, outbox links and payload hashes, reminder versions, broadcast audience/counter evidence, lifecycle checks, and exact RBAC permissions.
- `worker.js` is a real runtime: it validates configuration/MySQL capability, claims bounded leased batches with `SKIP LOCKED`, calls only Telegram `sendMessage`, applies exponential/retry-after delays, and drains cleanly.
- `scheduler.js` is a real runtime: a distributed database lease guards due reminder and broadcast materialization, with bounded batches and deterministic deduplication keys.
- Template validation uses a closed placeholder and HTML contract, escapes every variable, restricts buttons to HTTPS, supports previews without sending, and preserves immutable revisions.
- Referral attribution, referral activation, and approved/rejected withdrawal state changes enqueue active templates inside their existing transactions. Monetary placeholders format integer minor units without floating point.
- Broadcast creator/approver separation is enforced by both service rules and schema constraints. Cancellation affects unsent work and preserves delivery evidence.
- User notification routes and Admin template/reminder/broadcast routes retain authentication, CSRF, rate limits, IP policy, strict validation, exact permissions, optimistic concurrency, and audit context.

## Verification

Phase 16 adds **17 focused tests** across unit, integration, and security suites. They cover template injection, escaped substitution, HTTPS buttons, strict internal payloads, leases, exponential retry, redacted failures, malformed provider success responses, timezone scheduling, integer money formatting, creator/approver separation, user inbox auth/CSRF, exact permissions, immutable migration evidence, audience freezing, and worker method allowlisting.

The complete suite contains **311 tests**. The database verifier confirms **21 migrations, 6 seeds, 74 domain tables, 235 named constraints, 172 up statements, 154 down statements, and 19 seed statements**.

## Operational boundary

No live MySQL migration, Telegram send, webhook change, feature enablement, or deployment mutation was performed. Default reminder and broadcast flags remain disabled, and default templates remain drafts. Operators must review, publish, test, monitor, and then enable them.

Telegram delivery is explicitly at-least-once around provider acknowledgement loss; the Telegram Bot API does not accept an application idempotency key for `sendMessage`. Application replays are deduplicated, while that narrow provider-level duplicate risk remains documented rather than hidden.

**Phase 16 status: COMPLETE — focused tests 17/17; full quality gate passed 311/311.**

Next: Phase 17 — leaderboard, earning history, analytics rollups, and performance-oriented reporting.