suaveplan/openspec/archive/2026-05-19-add-delivery-tracking/tasks.md

Tasks — Add @suaveplan/delivery-tracking

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/delivery-tracking.md end-to-end
• 1.2 Confirm openspec/specs/delivery-tracking/spec.md does not yet exist
• 1.3 Read openspec/AGENTS.md Sections 0a, 2a, 6a, 7, 12, 13, 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill in ## Source mapping table — every requirement cites a line range OR is justified
• 1.6 Draft specs/delivery-tracking/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Types in src/types/delivery-tracking.types.ts
• 2.2 DeliveryTrackingError + defineCodes registry
• 2.3 OTel counter set in src/otel/instruments.ts
• 2.4 DeliveryEventStore interface + InMemoryDeliveryEventStore + computeStats helper
• 2.5 SurrealDeliveryEventStore using positional SurQL with typed-error wrapping
• 2.6 DeliveryTracker with Zod boundary, lifecycle dedupe, typed EventBus, injectable Clock/IdGenerator
• 2.7 DeliveryAggregator with campaign/contact/time-series APIs
• 2.8 TrackingPixelGenerator + TrackingLinkWrapper sharing a token-codec module
• 2.9 WebhookEventParser with sendgrid/mailgun/ses/generic parsers and a runtime registry
• 2.10 Package root barrel re-exports every public symbol via explicit named exports
• 2.11 Package vite.config.ts, vitest.config.ts, tsconfig.lib.json, tests/setup/polyfills.ts

3. Tests

• 3.1 Unit tests in each feature directory
• 3.2 OTel counter assertions via real InMemoryMetricExporter + MeterProvider
• 3.3 Every it(...) carries { timeout: 5000 }
• 3.4 No vitest / bun:test direct imports — every test imports from @suaveplan/testing/runner

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README.md links every co-located .md under ## Modules

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome clean
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/delivery-tracking
• 5.3 bunx turbo test:coverage --filter=@suaveplan/delivery-tracking — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/delivery-tracking
• 5.5 bunx turbo build --filter=@suaveplan/delivery-tracking

6. Pre-archive 9-row checklist

• 6.1 Generics threaded; injectable Clock/IdGenerator pinned via tests
• 6.2 Zod schemas wired at the tracker boundary
• 6.3 Every error code thrown by ≥1 production path (INVALID_INPUT/INVALID_TOKEN/UNSUPPORTED_PROVIDER/STORE_FAILURE/QUERY_FAILURE)
• 6.4 Strict-mode behaviours (exactOptionalPropertyTypes, noUncheckedIndexedAccess) honoured
• 6.5 OTel instruments emitted and asserted with real MeterProvider
• 6.6 Lifecycle dedupe tested (opened + delivered dedupe; clicked + sent allowed to repeat)
• 6.7 No retroactive ticking — boxes 5.* and 6.* tick only after the gates pass
• 6.8 No export * in feature barrels (all feature index.ts files use explicit named exports)
• 6.9 No direct vitest / bun:test imports (every test file imports from @suaveplan/testing/runner)

7. Archive

• 7.1 Fold specs/delivery-tracking/spec.md into openspec/specs/delivery-tracking/spec.md
• 7.2 Move openspec/changes/add-delivery-tracking/ → openspec/archive/2026-05-19-add-delivery-tracking/