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

Tasks: enterprise-payment

Change ID: enterprise-payment Package: @suaveplan/payment Target path: universal/commerce/payment Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/idempotency, @suaveplan/crypto, @suaveplan/fsm

---

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/commerce/payment/ 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 — PaymentStatus, PaymentIntent, PaymentTransition, Receipt, CreatePaymentOptions, PaymentWebhookEvent, PaymentAdapter (interface), PaymentStore (interface), PaymentServiceOptions.
• src/types/common.md (≥200 words, both examples, API reference).
• src/error-codes.ts — PaymentErrorCode (8 codes), metadata, register, eager call.
• src/constants/index.ts — ALLOWED_TRANSITIONS map, TERMINAL_STATUSES set, DEFAULT_CLOCK_SKEW_MS = 300_000.
• src/types/schemas.ts + schemas.md — Zod schemas. Note: PaymentIntent schema must NOT include pan, cvv, or expiry fields.

---

3. Core modules

• src/core/payment-fsm/ — PaymentFsm: wraps @suaveplan/fsm; defines all valid transitions per ALLOWED_TRANSITIONS; transition(intent, to, key) checks legality, throws PAYMENT_INVALID_TRANSITION if illegal, returns new PaymentIntent with updated status and appended PaymentTransition. Tests: all legal transitions, two illegal transitions, transition adds history entry.
• src/webhook/webhook-verifier/ — WebhookVerifier.verify(body, secret, timestamp, signature): constant-time HMAC via @suaveplan/crypto; checks |now - timestamp| <= skewMs; throws PAYMENT_SIGNATURE_FAILED on mismatch, PAYMENT_SIGNATURE_FAILED on expired. Tests: valid, tampered, expired, missing timestamp.
• src/receipt/receipt-generator/ — generateReceipt(intent): Receipt: maps intent fields; formattedAmount uses Intl.NumberFormat with currency. Tests: GBP formatting, USD formatting, partial refund status, all terminal statuses.
• src/utils/amount.ts — formatAmount, toMinorUnits, fromMinorUnits, addAmounts, subtractAmounts. subtractAmounts throws PAYMENT_AMOUNT_INVALID if result < 0. Tests: all functions, negative subtraction throws.
• src/core/payment-service/ — PaymentService: create, authorise, capture, refund, cancel — each wraps state transition with idempotency guard (from options.idempotency); calls options.adapter for provider interaction; stores result in options.store; emits event on options.bus. getReceipt(intentId) fetches from store and calls generateReceipt. Tests: happy path create→authorise→capture, duplicate idempotency key returns cached result, refund > captured amount throws, cancel from terminal state throws.

---

4. OTel instrumentation

• Span payment.transition with attributes payment.from_status, payment.to_status, payment.provider; counter payment.transition_total; histogram payment.transition_duration_ms.

---

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

• State machine reachability: every valid create→terminal path through ALLOWED_TRANSITIONS terminates in captured, refunded, failed, or cancelled.
• Amount arithmetic: addAmounts(a, b) === addAmounts(b, a) for non-negative integers; fromMinorUnits(toMinorUnits(x, 'GBP'), 'GBP') === x for 0–1 000 000.

---

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

• PaymentFsm.transition 100 000 times.
• generateReceipt 100 000 times.

---

7. Docs + verify

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