Sprint 5: stats endpoint + data integrity — transactional ingestion, impression beacon, registered event types

[hynding]

Summary

Implements the Sprint 5 plan (docs/superpowers/plans/2026-07-07-sprint-5-stats-integrity.md) — the first v1.x sprint, themed "trustworthy numbers": fix the write path, then build the stats read path on top.

• Transactional ingestion (closes Make event ingestion transactional (dedup records receipt, not completion) #2): new IngestionStore wraps event dedup-insert → progress increments → unlock inserts → usage in one db.transaction; a mid-chain failure rolls back the event row too, so dedup now records completion and SDK retries re-process instead of silently skipping
• Race-free progress (closes Fix lost-update race on achievement progress counters #3): increments happen in SQL (LEAST(current + delta, target) … RETURNING current); evaluateEvent returns deltas and the post-increment value decides unlocks — concurrent events can no longer lose updates (Testcontainers race + rollback tests)
• Accurate impressions (closes Offer impression accuracy: dismissed offers, retry duplicates, priority tie determinism #6): the placements GET no longer records impressions; the Placement widget fires an idempotent POST /v1/offers/:id/impression beacon only after the render decision passes the dismissal check (partial unique index dedups retries); resolveOffer gains a deterministic equal-priority tie-break
• Validated config plane (closes Validate config-plane responses in adapter-strapi + test verifyKey cache paths #4): all six adapter-strapi fetches are zod-validated (parse failure = fetch error → stale-on-error); verifyKey fails closed on bad enums with a warn log; the three missing cache-path tests added
• Registered event types: opt-in per project; unknown types get 400 unregistered_event_type with a Levenshtein did-you-mean suggestion
• GET /v1/stats (secret-key-only): totals + per-achievement/offer (CTR)/timed-event participation, optional from/to range; SDK gains a server-side-only secretKey option + getStats(); demo gets a server-rendered /stats page (sk never reaches the browser)

Behavior note for existing clients

One intentional wire-content change on POST /v1/events: the progress array now includes achievements already at target (clamped current = target) where it previously omitted them. Schema-compatible; spec-intended (evaluation no longer skips — SQL clamping makes at-target increments no-ops).

Test plan

• 72 API tests (stats, beacon, typo rejection among them); adapter-db Testcontainers suite covers the concurrency race, transaction rollback, beacon idempotency, and stats aggregation (range boundaries, cross-tenant isolation)
• All 3 Playwright specs passed live, including new assertions: exactly one impression POST on render, zero after dismiss+reload, and the /stats page correlating the actual unlocked achievement
• Live curls: sk → real aggregates, pk → 403; full pnpm turbo run typecheck build test green (27/27, re-verified post fix-wave)

Review notes

Ten tasks through the full implement→review gate cycle plus a final whole-branch review — verdict ready to merge with fixes, fix wave applied and re-approved (e68b73f: verify-key validation warn + fail-closed comment, delta rounding rationale). Follow-ups filed: #13 (offer-id validation on impression/click — stats pollution hardening), #14 (test-hardening bundle), #15 (stats polish bundle). Migration 0003 is safe on existing data (partial unique index predicate excludes all pre-existing rows).

🤖 Generated with Claude Code