suaveplan/openspec/archive/2026-05-25-enterprise-sms/proposal.md

Enterprise migration: @suaveplan/sms

• Change ID: enterprise-sms
• Status: PROPOSED
• Capability: sms
• Target package: @suaveplan/sms at 0.1.0
• Target path: packages/communication/messaging/sms/
• Design: ./design.md
• Spec delta: ./specs/sms/spec.md
• Source on main: /mnt/s/web/suaveplan/packages/server/sms (~1389 LOC)
• Enterprise plan: /mnt/s/web/suaveplan/enterprise/sms.md

Why

@suaveplan/sms is the universal SMS core: a provider-agnostic sending pipeline with template rendering, opt-out management, rate limiting, scheduling, retry, and delivery tracking. Providers (Twilio, Vonage, MessageBird, AWS SNS, in-house gateways) plug into the abstract SmsProvider contract.

The upstream package (v1.0.2) is functionally narrow — provider seam, template render, opt-out list, four events — but is missing every enterprise lever the genesis tree commits to:

• BaseError legacy hierarchy instead of defineCodes("SMS", [...]).
• No Zod boundary on SmsMessage, SmsTemplate, SmsProvider inputs.
• No OpenTelemetry counters or histograms.
• No retry/backoff on transient provider failures.
• No scheduling (sendAt) or batched dispatch.
• No rate limiting per provider / per recipient.
• No delivery-receipt ingest pipeline; status is fetched on demand.
• No AbortSignal propagation on send / scheduler / status pulls.
• No in-memory test provider; tests use ad-hoc anonymous mocks.
• One global event-emitter shape; no typed EventBus bridge.
• Tests pass with vi-mocks (@suaveplan/testing vi.fn()) — fine for unit harnesses, but the package never exercises a real provider round-trip end-to-end.

This change rewrites the package on genesis at enterprise quality while preserving every upstream export, then layers the SMS-core features (MessageScheduler, RateLimiter, DeliveryTracker, RetryPolicy, OTel instruments, Zod boundaries, abort signals, EventBus bridge, in-memory test provider).

Parity Checklist

Capability	Upstream	Migrated	Notes
SmsService send / template render / opt-out	✅	✅	Preserved verbatim, plus rate-limit + abort + retry on top.
SmsProvider abstract contract	✅	✅	Preserved (name, send, getStatus).
SmsTemplate ({{var}} substitution)	✅	✅	Preserved + defaults map + escape pass.
SmsMessage / SmsDeliveryReport / SmsDeliveryStatus	✅	✅	Preserved + Zod schemas.
OptOutEntry registry	✅	✅	Preserved + bulk import / export.
SmsEventMap (sms.sent/delivered/failed/opted_out/opted_in)	✅	✅	Preserved + new sms.scheduled / sms.retry / sms.rate_limited.
Legacy EventEmitter surface (on/off/emit)	✅	✅	Preserved (delegates to typed EventBus).
SmsError legacy class + factory methods	✅	✅	Preserved as back-compat alias over genesis defineCodes family.
respondProblemJson Hono helper	✅	✅	Preserved.
registerSmsErrorCodes / SMS_ERROR_METADATA	✅	✅	Preserved via genesis ErrorCodes.registerMany.
Stable SMS.* defineCodes registry	🚫 (legacy BaseError)	⬆️	Genesis addition.
Zod boundary on every public input	🚫	⬆️	Genesis addition.
OTel counters + histogram	🚫	⬆️	Genesis addition (4 instruments).
MessageScheduler (sendAt + cancel)	🚫	⬆️	Genesis addition.
RateLimiter (token bucket per recipient)	🚫	⬆️	Genesis addition.
DeliveryTracker (receipt ingest + cache)	🚫	⬆️	Genesis addition.
RetryPolicy (exponential backoff w/ jitter)	🚫	⬆️	Genesis addition.
InMemorySmsProvider (test provider)	🚫	⬆️	Genesis addition; replaces ad-hoc test mocks.
AbortSignal propagation	🚫	⬆️	Genesis addition.
100/100/100/100 coverage	🚫	⬆️	Genesis gate.

What

A net-new package at packages/communication/messaging/sms/ at 0.1.0, universal tier (no Node/Bun-only APIs), Zod-validated boundaries, OTel-instrumented, with the full upstream public surface plus the genesis enterprise additions.

This is the SMS core — not the providers package. The abstract SmsProvider interface ships with an in-memory test provider (InMemorySmsProvider) so consumers and integration tests can run without external services. Concrete provider integrations (Twilio, Vonage, AWS SNS) ship in the sibling @suaveplan/sms-providers package next wave.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/sms to enumerate.

No genesis package currently imports @suaveplan/sms:

• @suaveplan/sms-providers — pending migration, will consume this as workspace:^0.1.0. [x] no action needed (reason: package not yet on genesis)
• @suaveplan/api-plugin-messaging — pending migration. [x] no action needed (reason: package not yet on genesis)

Foundation deps (@suaveplan/error, @suaveplan/events, @suaveplan/types) are read-only consumers; no change required.

Out of scope

Nothing. Per feedback_no_deferrals_on_migration.md and AGENTS §2b, no "phase 2" is permitted. The whole upstream surface plus the enterprise additions land here, feature-complete, with 100/100/100/100 coverage.