feat(analyticsevent): backend→NR custom-event bridge (WS4-P1, F1) (#44)

Add common/analyticsevent — the foundation for the WS4 behavioral-
intelligence layer. Before this, `grep RecordCustomEvent api/ worker/`
returned 0 hits, so funnel KPIs (anon→claimed, claimed→paid) and the
synthetic InstantFlowTest matrix had no way to reach New Relic.

Shaped like storageprovider/queueprovider/featureflag: one Emitter
interface, swappable backends via Factory(ANALYTICS_BACKEND), with the
NR Go-agent dep quarantined in the analyticsevent/nr subpackage so noop-
only consumers don't pull it into their import graph.

- Emitter.Record(ctx, eventType, attrs) — fire-and-forget, no error return.
- Backends: noop (default, zero-dep, never errors) + newrelic (wraps an
  existing *newrelic.Application via Config.Override → RecordCustomEvent).
- FAIL OPEN (inverse of featureflag's fail-closed): Wrap recovers every
  panic and swallows sink errors so analytics never blocks/errors a
  request path; degrade ladder always returns a usable noop emitter.
- PII allowlist: Sanitize default-denies every key not in AllowedAttributes;
  email is hashed (sha256(lower(trim))[:16]) into emailHash, never raw —
  no tokens/connection strings can escape. Enforced at the Wrap chokepoint.
- Well-known event types + attr constants: InstantFunnel, InstantFlowTest,
  InstantChurnSignal, InstantAbuseSignal; typed FlowTest{flow,actor,tier,
  layer,result,latencyMs,commitId,...} helper matching the synthetics plan.
- nr sink exposes a FailureHook seam so services wire
  instant_analytics_emit_failed_total without common knowing the metrics lib.

NOT wired into api/worker here (one-tree discipline; per-service emit-site
PRs follow). Package + tests only.

Tests: 100% coverage both packages. go build/vet/test ./... green.
golangci-lint 0 issues. govulncheck clean on the dep tree (NR v3.43.3 =
the version already in worker; only 3 stdlib findings, all tied to the
local go1.26.2 toolchain, fixed in 1.26.3/1.26.4 — not in this code's path).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mastermanas805

analyticsevent/analyticsevent.go

@@ -0,0 +1,59 @@
+package analyticsevent
+
+import "context"
+
+// Wrap decorates a concrete [Emitter] with the package's two non-negotiable
+// guarantees:
+//
+//  1. FAIL OPEN — a panic inside the backend's Record (or Close) is recovered
+//     and swallowed so an analytics hiccup can NEVER crash or error a caller's
+//     request path. Record has no error return, so swallowing is the contract.
+//  2. PII — every attribute map is run through [Sanitize] (allowlist + email
+//     hashing) BEFORE the concrete backend sees it, so no backend can emit a
+//     raw email / token / connection string even if an emit site passed one.
+//
+// This is the single chokepoint that makes the package contract true. Factory
+// always returns a wrapped emitter, so no call site holds a raw backend.
+//
+// Wrapping is idempotent: Wrap(Wrap(e)) behaves identically to Wrap(e). A nil
+// backend wraps to the no-op emitter (the most fail-open emitter possible).
+func Wrap(e Emitter) Emitter {
+	if e == nil {
+		return wrapped{inner: NewNoop()}
+	}
+	if w, already := e.(wrapped); already {
+		return w
+	}
+	return wrapped{inner: e}
+}
+
+// wrapped is the fail-open + PII-sanitizing decorator. Unexported; construct via
+// [Wrap]. Value receiver (it holds only an interface) so it is cheap to copy and
+// the idempotency type-assertion in Wrap is straightforward.
+type wrapped struct {
+	inner Emitter
+}
+
+// Record sanitizes attrs (allowlist + email-hash) then forwards to the backend,
+// recovering and swallowing any panic so the caller's path is never affected.
+func (w wrapped) Record(ctx context.Context, eventType string, attrs map[string]any) {
+	defer func() { _ = recover() }() // fail open: analytics must never panic upward
+	if eventType == "" {
+		return // a typeless event is meaningless and un-queryable; drop it
+	}
+	w.inner.Record(ctx, eventType, Sanitize(attrs))
+}
+
+// Name reports the wrapped backend's name (the wrapper is transparent).
+func (w wrapped) Name() string { return w.inner.Name() }
+
+// Close delegates to the backend, swallowing any panic so teardown of one
+// service never crashes on a misbehaving emitter.
+func (w wrapped) Close() (err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			err = nil // fail open: teardown is best-effort, never panic upward
+		}
+	}()
+	return w.inner.Close()
+}

analyticsevent/analyticsevent_test.go

@@ -0,0 +1,147 @@
+package analyticsevent
+
+import (
+	"context"
+	"sync"
+	"testing"
+)
+
+// recorder is a test Emitter that captures everything it sees AFTER the wrapper
+// sanitized it, so tests can assert the wrapper applied Sanitize.
+type recorder struct {
+	mu       sync.Mutex
+	events   []capturedEvent
+	panicOn  string // eventType to panic on (to exercise fail-open)
+	closed   bool
+	closeErr error
+}
+
+type capturedEvent struct {
+	eventType string
+	attrs     map[string]any
+}
+
+func (r *recorder) Record(_ context.Context, eventType string, attrs map[string]any) {
+	if eventType == r.panicOn {
+		panic("backend blew up")
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.events = append(r.events, capturedEvent{eventType, attrs})
+}
+func (r *recorder) Name() string { return "recorder" }
+func (r *recorder) Close() error {
+	r.closed = true
+	return r.closeErr
+}
+func (r *recorder) last() capturedEvent {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if len(r.events) == 0 {
+		return capturedEvent{}
+	}
+	return r.events[len(r.events)-1]
+}
+func (r *recorder) count() int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return len(r.events)
+}
+
+func TestWrap_SanitizesBeforeBackend(t *testing.T) {
+	rec := &recorder{}
+	e := Wrap(rec)
+	e.Record(context.Background(), EventFunnel, map[string]any{
+		AttrEmail:  "secret@user.com",
+		"password": "nope",
+		AttrTier:   "pro",
+	})
+	got := rec.last()
+	if got.eventType != EventFunnel {
+		t.Fatalf("eventType = %q, want %q", got.eventType, EventFunnel)
+	}
+	if _, ok := got.attrs[AttrEmail]; ok {
+		t.Error("wrapper did not strip raw email before backend")
+	}
+	if _, ok := got.attrs["password"]; ok {
+		t.Error("wrapper did not strip non-allowlisted key before backend")
+	}
+	if got.attrs[AttrEmailHash] != HashEmail("secret@user.com") {
+		t.Error("wrapper did not hash email before backend")
+	}
+	if got.attrs[AttrTier] != "pro" {
+		t.Error("wrapper dropped an allowlisted key")
+	}
+}
+
+func TestWrap_FailOpenOnPanic(t *testing.T) {
+	rec := &recorder{panicOn: EventFunnel}
+	e := Wrap(rec)
+	// Must NOT panic into the caller.
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("wrapper let backend panic escape: %v", r)
+		}
+	}()
+	e.Record(context.Background(), EventFunnel, nil)
+	// A subsequent non-panicking event still works (wrapper isn't poisoned).
+	e.Record(context.Background(), EventChurnSignal, nil)
+	if rec.count() != 1 {
+		t.Fatalf("expected 1 captured (the non-panicking) event, got %d", rec.count())
+	}
+}
+
+func TestWrap_DropsEmptyEventType(t *testing.T) {
+	rec := &recorder{}
+	Wrap(rec).Record(context.Background(), "", map[string]any{AttrTier: "pro"})
+	if rec.count() != 0 {
+		t.Fatalf("empty eventType should be dropped, got %d events", rec.count())
+	}
+}
+
+func TestWrap_NilBackendIsNoop(t *testing.T) {
+	e := Wrap(nil)
+	if e.Name() != BackendNoop {
+		t.Fatalf("Wrap(nil).Name() = %q, want %q", e.Name(), BackendNoop)
+	}
+	// Must not panic.
+	e.Record(context.Background(), EventFunnel, map[string]any{AttrTier: "pro"})
+	if err := e.Close(); err != nil {
+		t.Fatalf("Wrap(nil).Close() = %v, want nil", err)
+	}
+}
+
+func TestWrap_Idempotent(t *testing.T) {
+	rec := &recorder{}
+	once := Wrap(rec)
+	twice := Wrap(once)
+	if once != twice {
+		t.Fatal("Wrap is not idempotent: Wrap(Wrap(e)) != Wrap(e)")
+	}
+}
+
+func TestWrap_CloseDelegatesAndRecoversPanic(t *testing.T) {
+	rec := &recorder{}
+	if err := Wrap(rec).Close(); err != nil {
+		t.Fatalf("Close = %v, want nil", err)
+	}
+	if !rec.closed {
+		t.Fatal("Close did not delegate to backend")
+	}
+
+	// A panicking Close is swallowed (returns nil).
+	pc := &panicCloser{}
+	if err := Wrap(pc).Close(); err != nil {
+		t.Fatalf("panicking Close should be swallowed to nil, got %v", err)
+	}
+}
+
+type panicCloser struct{ recorder }
+
+func (*panicCloser) Close() error { panic("close blew up") }
+
+func TestWrap_NameTransparent(t *testing.T) {
+	if Wrap(&recorder{}).Name() != "recorder" {
+		t.Fatal("wrapper should be transparent for Name()")
+	}
+}

analyticsevent/events.go

@@ -0,0 +1,172 @@
+package analyticsevent
+
+import (
+	"context"
+	"time"
+)
+
+// Well-known custom event types. Every emit site MUST use one of these
+// constants, never an inline string literal (repo convention: no scattered
+// strings; CLAUDE.md rule 16: a single source for each contract token). New
+// Relic indexes events by eventType, so a typo creates a silent second event
+// table that no dashboard queries.
+const (
+	// EventFunnel is the conversion-funnel event emitted at each step of the
+	// acquisition journey (landing -> provision -> claim -> paid). Faceted by
+	// AttrFunnelStep + AttrActor to compute anon->claimed and claimed->paid.
+	EventFunnel = "InstantFunnel"
+
+	// EventFlowTest is one synthetic flow-test result per UI/API flow per tick,
+	// pushed by the worker's synthetic prober. Carries cohort="synthetic" so
+	// every other dashboard can exclude this traffic from real KPIs.
+	EventFlowTest = "InstantFlowTest"
+
+	// EventChurnSignal flags a behavioral churn indicator on a paid team (e.g.
+	// no activity in N days). Feeds the churn-trend tile (WS4-P5).
+	EventChurnSignal = "InstantChurnSignal"
+
+	// EventAbuseSignal flags an abuse indicator (fingerprint dedup-cap hit,
+	// quota burn, recycle-seen spike). Feeds the abuse behavioral tile (WS4-P6).
+	EventAbuseSignal = "InstantAbuseSignal"
+)
+
+// Canonical funnel-step values for the AttrFunnelStep attribute on
+// [EventFunnel]. Low-cardinality and stable so NRQL FACETs stay clean.
+const (
+	FunnelStepLanding   = "landing"   // onboarding URL first hit
+	FunnelStepProvision = "provision" // a resource was provisioned
+	FunnelStepClaim     = "claim"     // anonymous -> claimed (account created)
+	FunnelStepPaid      = "paid"      // claimed -> paid (subscription active)
+)
+
+// Canonical actor classes for the AttrActor attribute (mirrors plan F2's
+// actor-classification middleware). Low cardinality (safe NR attribute).
+const (
+	ActorAgentClaude    = "agent_claude"
+	ActorAgentMCP       = "agent_mcp"
+	ActorAgentCurl      = "agent_curl"
+	ActorAgentOther     = "agent_other"
+	ActorHumanDashboard = "human_dashboard"
+	ActorProber         = "prober"
+	ActorUnknown        = "unknown"
+)
+
+// Canonical flow-test result values for the AttrResult attribute on
+// [EventFlowTest].
+const (
+	ResultPass = "pass"
+	ResultFail = "fail"
+	ResultSkip = "skip"
+)
+
+// CohortSynthetic is the AttrCohort value every synthetic flow-test event
+// carries so real-traffic dashboards can exclude it (WHERE cohort != 'synthetic').
+const CohortSynthetic = "synthetic"
+
+// Canonical attribute keys. Emit sites and dashboards (NRQL FACET / WHERE)
+// MUST use these exact strings. Every key here that is non-PII is also in
+// [AllowedAttributes]; AttrEmail is the ONE PII key and is hashed (never
+// emitted raw) by [Sanitize].
+const (
+	// Identity / segmentation (non-PII; allowlisted).
+	AttrActor         = "actor"         // agent_* / human_* / prober / unknown
+	AttrTier          = "tier"          // anonymous, free, hobby, pro, ...
+	AttrEnv           = "env"           // development, production, ...
+	AttrCohort        = "cohort"        // "synthetic" or "" for real traffic
+	AttrTeamID        = "teamId"        // team UUID (an opaque id, not PII)
+	AttrResourceToken = "resourceToken" // resource token UUID (opaque id)
+	AttrFingerprint   = "fingerprint"   // SHA256(/24+ASN) bucket hash (already hashed)
+	AttrCommitID      = "commitId"      // deploy SHA, ties failures to a deploy
+	AttrServiceName   = "serviceName"   // emitting service: api / worker / provisioner
+
+	// Funnel (non-PII; allowlisted).
+	AttrFunnelStep = "funnelStep" // landing / provision / claim / paid
+
+	// Flow-test (non-PII; allowlisted).
+	AttrFlow           = "flow"           // db_new, cache_new, deploy_new, ...
+	AttrLayer          = "layer"          // api / ui / e2e
+	AttrResult         = "result"         // pass / fail / skip
+	AttrReason         = "reason"         // short failure reason (free text, no PII)
+	AttrLatencyMs      = "latencyMs"      // observed latency in milliseconds
+	AttrSyntheticRunID = "syntheticRunId" // groups all flows from one prober tick
+
+	// Generic event metadata (non-PII; allowlisted).
+	AttrService    = "service"    // free-form sub-service / handler name
+	AttrReasonCode = "reasonCode" // enum-ish machine reason for churn/abuse signals
+
+	// PII — NOT allowlisted as-is. Email under this key is HASHED by Sanitize
+	// into AttrEmailHash; the raw value is dropped.
+	AttrEmail = "email"
+
+	// AttrEmailHash carries sha256(lower(trim(email)))[:16]. This IS allowlisted
+	// — it is the only form an email may take in an event.
+	AttrEmailHash = "emailHash"
+)
+
+// FlowTest is the typed payload for an [EventFlowTest] custom event, matching
+// the synthetic-prober contract in TEST-ACCOUNTS-AND-NR-SYNTHETICS-PLAN.md §3.3.
+// Use [Emitter] with [FlowTest.Attrs] (or the [RecordFlowTest] helper) instead
+// of hand-building the attribute map at each call site.
+type FlowTest struct {
+	// Flow is the flow under test ("db_new", "cache_new", "deploy_new", ...).
+	Flow string
+	// Actor is the simulated caller class (one of the Actor* constants).
+	Actor string
+	// Tier is the plan tier the synthetic run exercised ("anonymous", "pro", ...).
+	Tier string
+	// Layer is which layer was probed ("api", "ui", "e2e").
+	Layer string
+	// Result is the outcome (one of the Result* constants).
+	Result string
+	// LatencyMs is the observed end-to-end latency in milliseconds.
+	LatencyMs int64
+	// Reason is a short, PII-free failure reason (empty on pass).
+	Reason string
+	// CommitID is the api /healthz commit_id at run time (ties a failure to the
+	// deploy that caused it).
+	CommitID string
+	// SyntheticRunID groups every flow from one prober tick (UUID).
+	SyntheticRunID string
+}
+
+// Attrs renders a [FlowTest] into the flat attribute map an [Emitter] consumes.
+// Cohort is always [CohortSynthetic] for flow tests. Empty fields are omitted so
+// an absent value reads as "missing" (not "") in NRQL. The result is already
+// allowlist-clean (no PII keys) but still passes through [Sanitize] in Record.
+func (f FlowTest) Attrs() map[string]any {
+	out := make(map[string]any, 9)
+	putStr(out, AttrFlow, f.Flow)
+	putStr(out, AttrActor, f.Actor)
+	putStr(out, AttrTier, f.Tier)
+	putStr(out, AttrLayer, f.Layer)
+	putStr(out, AttrResult, f.Result)
+	putStr(out, AttrReason, f.Reason)
+	putStr(out, AttrCommitID, f.CommitID)
+	putStr(out, AttrSyntheticRunID, f.SyntheticRunID)
+	out[AttrLatencyMs] = f.LatencyMs
+	out[AttrCohort] = CohortSynthetic
+	return out
+}
+
+// RecordFlowTest is the ergonomic typed helper for the synthetic prober: it
+// builds the [EventFlowTest] attribute map from a [FlowTest] and records it.
+// Fire-and-forget, same fail-open contract as [Emitter.Record].
+func RecordFlowTest(ctx context.Context, e Emitter, f FlowTest) {
+	if e == nil {
+		return
+	}
+	e.Record(ctx, EventFlowTest, f.Attrs())
+}
+
+// putStr sets out[key]=val only when val is non-empty, so callers can build a
+// map without "" placeholders polluting NRQL facets.
+func putStr(out map[string]any, key, val string) {
+	if val != "" {
+		out[key] = val
+	}
+}
+
+// nowUnixMilli is a package var so tests can pin the clock if a future event
+// needs a server-stamped timestamp. Unused by the current event set (NR stamps
+// its own timestamp), retained as the single time source if one is added.
+var nowUnixMilli = func() int64 { return time.Now().UnixMilli() }