billing: validate + redeem admin-issued promo codes alongside plans-yaml codes

[mastermanas805]

Summary

Unify the two promo-code sources at POST /api/v1/billing/promotion/validate and wire single-use redemption into the Razorpay webhook path.

• Validate handler now checks the plans-yaml registry first (PR billing: POST /api/v1/billing/promotion/validate — HTTP wrapper around plans.validatePromotion #47 behaviour preserved verbatim), then falls back to admin_promo_codes (PR admin: Customers endpoints (list/detail/tier-change/issue-promo) gated on ADMIN_EMAILS #48 table) on the not found branch. Returns one of the existing error codes plus a new promotion_already_used with a distinct agent_action sentence.
• Checkout accepts promotion_code in the body; when it matches an admin_promo_codes row for the calling team, the Razorpay subscription is created with notes.admin_promo_code_id = <row.id>.
• subscription.charged webhook reads that notes key and best-effort flips admin_promo_codes.used_at = now(). Race-safe via UPDATE ... WHERE used_at IS NULL.

How admin_promo_codes.kind maps to PR #47's response shape

admin_promo_codes column	response.discount field	mapping
kind (percent_off/first_month_free/amount_off)	discount.kind	passthrough — same enum
value (int)	discount.value	passthrough
(n/a — admin codes are team-scoped)	discount.applies_to	echo the requested plan: []string{plan}
(always single-use)	discount.max_uses	hardcoded 1
(no description column)	discount.description	synthesized: "40% off (admin-issued, single use)"
expires_at (timestamptz)	valid_until	RFC3339 (more precise than the plans-yaml YYYY-MM-DD path)

Pushback / divergences from the brief

1. "applies-to includes the requested plan" doesn't map onto migration 021 — admin_promo_codes.applies_to is INTEGER (a percent_off cap in cents per openapi.go), not a list of tier names. Admin codes are scoped by team_id, not plan; the handler does not reject by plan. The dashboard still sees a populated applies_to array (echoes the requested plan), so the UI stays uniform across both code sources.
2. "Validate admin code for wrong plan → promotion_invalid" therefore doesn't fire — admin codes apply to any plan the team subscribes to. The plans-yaml wrong-plan branch (LAUNCH50 against hobby) is still covered.
3. "Already accepts promotion_code (from PR obs: provisioner service observability — slog default, NR agent, gRPC interceptor, healthz sidecar (track 5/8) #38)" — checkout did NOT yet accept promotion_code. Added it as part of this PR.
4. "On subscription.activated, mark used_at" — our webhook hooks subscription.charged (the event that drives the tier upgrade). Used the same hook for redemption symmetry; comment in maybeMarkAdminPromoCodeUsed documents the choice.
5. End-to-end checkout-stamps-notes test is not included because it would require mocking razorpay-go. The contract is covered by validate-time tests + the webhook redemption test; the named constant checkoutNoteAdminPromoCodeID is read by both call sites so they cannot drift.

Test plan

• make test-unit green — all 25 packages, including 13 new tests in billing_promotion_redeem_test.go.
• TestAgentActionContract green — covers the two new agent_action constants (AgentActionPromotionAlreadyUsed, AgentActionPromotionExpired).
• Plans-yaml regression: TestValidatePromotion_PlansYamlCode_StillWorks confirms plans-yaml codes never fall through to the admin lookup when present.
• Concurrency: TestMarkAdminPromoCodeUsed_Race_OnlyOneWins confirms exactly one of two racing callers succeeds at the model boundary.

🤖 Generated with Claude Code