15 — Engagement signal & marketing-send flow

Status: Draft Date: 2026-06-20 Owner: engagement + legal (15 engagement-marketing) Related spec: docs/superpowers/specs/2026-05-23-15-engagement-marketing-design.md §2–§4

Purpose

Single end-to-end view of how an engagement/marketing contact is produced and delivered: which producer emits which signal, where the consent gate sits, how the notify-queue fans out to push vs email, and where the sealed-bid + double-opt-in (DOI) + frequency invariants are enforced. This is the design-level companion to spec 15 §3 (“Cross-layer data flow”) and §2 (the seven layers); it does not introduce new contracts — the binding source is the spec.

Producer disposition (spec 15 §2.1)

Signal	Producer	Transport	Class
`bid.outbid`	AuctionDO (rank-1 loss)	DIRECT `/push/send`, one push per (auction, displaced user) — D49	transactional
`rank.climbed_to_top`	AuctionDO (#1 boundary, at-most-once via DO marker)	`notify-queue` → push dispatch	transactional-adjacent
`auction.closing_soon`	active-bidder cron lane	DIRECT `/push/send`	transactional
`auction.opened`	daily opener cron (today only)	`notify-queue` → consent gate → channel	MARKETING (DOI)
`calendar.day_of_interest`	daily calendar cron (flag + consent)	`notify-queue` → consent gate → channel	MARKETING (DOI)
`won` / `lost` / `this_close`	saga `bestEffortPush`	DIRECT `/push/send` (won/lost rate-cap-exempt)	must-deliver
admin campaign	`mkt-dispatch` hourly cron	`mkt_campaign_sends` claim → `notify-queue`	MARKETING (DOI)

Direct-seam transactional signals never traverse engagement orchestration or frequency-capping (spec 15 §2.5, guardrail 11).

Sequence — a marketing send (auction.opened / calendar / campaign)

Bounce / suppression backstop (spec 15 §2.4 B0, D56)

Invariants enforced along this path

Sealed-bid (§5): .strict() zod at the queue boundary; per-template var allow-list ({date}, {day}, {holiday_label}, {rank} ∈ {1,2,3} own coarse rank only); the campaign grammar rejects topic=closing_soon; the ledger has no amount/rank/competitor column and a schema test forbids any JOIN to amount-bearing surfaces.
DOI / UWG §7 (§6): no non-transactional email before confirmed consent + logged proof + working unsubscribe; resolveContactGate fail-closes; the DOI confirmation email rides the transactional apps/api/emails.ts seam, not this queue.
Best-effort everywhere (§2.0): every emit / ledger write is .catch()-swallowed or deadline-bounded; it never fails the bid hot path or the saga critical path.
Frequency subordination (§2.5): Orchestration owns its cap before /push/send, so a would-be-capped engagement push is never sent (not lost for 24h); transactional outbid/closing can never be starved.

Failure modes & recovery

Poison signal (smuggled amount / rank>3 / unknown member) → .parse() throws → message dead-letters loudly; never silently acked.
Resend transport throw → consumer retries; typed “no” (suppressed / capped) acks as terminal-for-day, not retried.
Export bundle not yet returning consent rows (D52) → the marketing email channel stays hard-blocked in production; push + transactional email ship first.