# Tasks — `@suaveplan/sms` enterprise migration

## 1. Package scaffold

- [ ] Create `packages/communication/messaging/sms/` with `package.json`, `tsconfig.lib.json`, `vite.config.ts`, `README.md`.
- [ ] Add deps: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`, `@opentelemetry/api`, `tslib`, `zod`; devdeps: `@suaveplan/testing`, `@opentelemetry/sdk-metrics`, `@vitest/coverage-istanbul`, `vitest`, `vite`, `vite-plugin-dts`, `typescript`.
- [ ] Subpath exports for every feature module + `./types`, `./routes/problem-json`.

## 2. Error codes

- [ ] `error-codes/error-codes.ts` — `defineCodes("SMS", [...])` with 13 codes, typed `SmsError` base, 12 leaf classes.
- [ ] `error-codes/error-codes.test.ts` — registry sort assertion + reachability test (every code raised from a real call site).
- [ ] `error-codes/error-codes.md`.

## 3. Legacy compatibility

- [ ] `legacy-errors/legacy-errors.ts` — back-compat `SmsError` class with the upstream `SmsErrorCode` union + factories (`invalidPhoneNumber`, `sendFailed`, `templateNotFound`, `recipientOptedOut`, `providerNotConfigured`).
- [ ] `legacy-errors/legacy-errors.test.ts`.
- [ ] `legacy-metadata/legacy-metadata.ts` — `SMS_ERROR_METADATA` + `registerSmsErrorCodes()` + `SmsRegisteredErrorCode`; eager-register on import.
- [ ] `legacy-metadata/legacy-metadata.test.ts`.

## 4. Types + schemas

- [ ] `types/sms.types.ts` — `SmsDeliveryStatus`, `SmsMessage`, `SmsDeliveryReport`, `SmsProvider`, `OptOutEntry`, `SmsTemplate`, `SmsEventMap`, `SmsServiceOptions`, `ScheduledMessage`, `ScheduleHandle`.
- [ ] `schemas/schemas.ts` — Zod for `SmsMessage`, `SmsTemplate`, `SmsDeliveryReport`, `SmsServiceOptions`; `parseSmsMessage` / `parseSmsTemplate` throw `SmsInvalidConfigError`.

## 5. Pipeline primitives

- [ ] `validation/phone.ts` — `isValidE164`.
- [ ] `templates/templates.ts` — `TemplateRegistry`, `renderTemplate(template, vars, defaults?)`.
- [ ] `opt-out/opt-out.ts` — `OptOutRegistry` (set/clear/check/bulk).
- [ ] `rate-limiter/rate-limiter.ts` — `RateLimiter` token-bucket with injectable `Clock`.
- [ ] `retry/retry.ts` — `RetryPolicy` exponential w/ jitter, abort-aware.
- [ ] `scheduler/scheduler.ts` — `MessageScheduler` with injectable `Timers`.
- [ ] `delivery-tracker/delivery-tracker.ts` — bounded LRU receipt cache.

## 6. In-memory provider

- [ ] `in-memory-provider/in-memory-provider.ts` — `InMemorySmsProvider` implementing `SmsProvider`; records sent messages, configurable per-send outcome (queued/sent/delivered/failed/undelivered), supports `simulateFailure`, supports `advance` for delivery state transitions.

## 7. OTel

- [ ] `otel/metrics.ts` — counters `sms.sent_total`, `sms.failed_total`, `sms.retry_total`; histogram `sms.send_duration_ms`; `refreshSmsMeters()`.

## 8. Service orchestrator

- [ ] `service/sms-service.ts` — `SmsService` extends/wraps `EventBus<SmsEventMap>`; constructor accepts `SmsServiceOptions` (Zod-validated); legacy `on/off/emit` mirrors against the bus; integrates rate-limiter + retry + scheduler + delivery-tracker; honours `AbortSignal`.
- [ ] `service/sms-service.test.ts` — full pipeline tests against `InMemorySmsProvider`.

## 9. Hono helper

- [ ] `routes/problem-json.ts` — `respondProblemJson` + `PROBLEM_JSON_CONTENT_TYPE`, mapping `SuaveplanError` / `HttpError` / unknown → problem+json.

## 10. Index barrel + sibling docs

- [ ] `src/index.ts` — explicit named re-exports of every public symbol.
- [ ] Sibling `.md` per `.ts` (≥200 words, 6 sections).
- [ ] Package-root `README.md` with quick start, modules table, install.

## 11. Verification

- [ ] `bunx turbo lint typecheck test build --filter=@suaveplan/sms` green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/sms` ≥ 100/100/100/100.
- [ ] Banned-pattern scan zero output (`TODO`, `FIXME`, `ts-ignore`, `.skip`, `.only`, `any`, `biome-ignore`).
- [ ] Test-runner-import scan zero output (`from "vitest"|"bun:test"`).
- [ ] All sibling `.md` present; `README.md` present.

## 12. Manifest + STATUS

- [ ] `bun scripts/folder-reorg/generate-manifest.ts` to refresh `MANIFEST.md`.
- [ ] STATUS.md: flip `@suaveplan/sms` `–` → `✅`, decrement Pending, increment Migrated.

## 13. Spec finalisation

- [ ] Fold `specs/sms/spec.md` into `openspec/specs/sms/spec.md`.
- [ ] Move change folder to `openspec/archive/2026-05-25-enterprise-sms/`.