suaveplan/openspec/changes/enterprise-campaigns/tasks.md

Tasks: enterprise-campaigns

Change ID: enterprise-campaigns Package: @suaveplan/campaigns Target path: universal/email/campaigns Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/email-templates, @suaveplan/audience-rules, @suaveplan/idempotency, @suaveplan/retry, @suaveplan/suppression

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create universal/email/campaigns/ with src/, tests/, src/__benchmarks__/ and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, correct exports map, dependencies, and devDependencies.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• src/types/common.ts — Campaign, CampaignStatus, CampaignSchedule, AbVariant, CampaignSendOptions, CampaignAnalytics, CampaignFilter, CampaignSender, CampaignManagerOptions.
• src/types/common.md (≥200 words, both examples, API reference).
• src/error-codes.ts — CampaignErrorCode (6 codes), metadata, register, eager call.
• src/types/schemas.ts + schemas.md — Zod schemas.

---

3. Core modules

• src/core/campaign-fsm/ — CampaignFsm: defines valid transitions between CampaignStatus values; illegal transitions throw CAMPAIGN_INVALID_TRANSITION. Tests: all valid paths, two invalid transition attempts.
• src/core/ab-bucketing/ — bucketRecipient(email, variants): AbVariant | undefined: FNV-1a hash of email, compare against cumulative fraction bounds. Tests: determinism (same input → same bucket), distribution across 10 000 random emails is within 5% of configured fraction.
• src/scheduling/schedule-parser/ — parseSchedule(schedule, clock): returns next fire Date for immediate/at/recurring. Validates cron expressions (5-field). Tests: immediate → now, at → future date, recurring → next slot, invalid cron throws.
• src/core/campaign-manager/ — CampaignManager: create, schedule, send, cancel, get, list. send iterates audience from @suaveplan/audience-rules, checks suppression per recipient, renders template per recipient (optionally with A/B variant), calls CampaignSender.send. Wraps each recipient delivery in idempotency guard. AbortSignal cancel mid-send. Tests: send happy path, abort mid-send, suppressed recipient is counted not sent, A/B variant selection, analytics returned correctly.
• src/analytics/campaign-analytics/ — aggregateResults(results): CampaignAnalytics. Tests: all-sent, mixed-failure, all-suppressed.

---

4. OTel instrumentation

• send: span campaign.send with attributes campaign.id, campaign.recipient_count; counter campaign.send_total; histogram campaign.send_duration_ms.

---

5. Property-based tests (tests/property.test.ts)

• A/B bucketing: for arbitrary variant fractions summing to ≤1, bucketRecipient always returns a variant within the configured set or undefined.
• FSM: any reachable path from draft reaches a terminal state (sent, cancelled, failed) in ≤4 transitions.

---

6. Benchmarks (src/__benchmarks__/campaigns.bench.ts)

• bucketRecipient for 100 000 recipients.

---

7. Docs + verify

• One .md per implementation file (≥200 words, both examples, API reference). Root README.md.
• bunx turbo lint typecheck test --filter=@suaveplan/campaigns — green.
• bunx turbo test:coverage --filter=@suaveplan/campaigns — 100%.
• bun scripts/publish.ts --package @suaveplan/campaigns.
• Archive: openspec/archive/2026-04-24-enterprise-campaigns/.