[Campaigns] Add per-recipient personalization, experiments, attribution, and conversion reporting #124

Parent epic: #79

Priority: P2 — scale and differentiation

Problem and current baseline

QuickVoice already imports recipient data for batch calls, accepts agent variables, records calls/extracted fields, and shows basic campaign progress. Operators cannot yet safely define typed per-recipient personalization with deterministic fallbacks, freeze exactly what a recipient heard, randomize variants without bias or overlap, register business goals, or report conversions with transparent attribution windows and evidence. This issue extends existing campaign variables and reporting; it must not imply causality from simple correlation.

User-visible outcome

An operator can map approved customer/campaign fields into a versioned message/workflow, preview representative recipients and missing-data behavior, run a controlled campaign experiment, and view outcome/conversion/cost reporting by variant and segment. Every recipient has a reproducible assignment and configuration snapshot, and reports clearly distinguish observed conversions, attributed conversions, and statistically uncertain lift.

Requirements

Personalization

• Define a typed, versioned campaign variable schema with name, type, source, allowed/default/null behavior, required/sensitive flags, formatting/locale rules, and description; validate values at import/snapshot and immediately before dispatch where live lookup is used.
• Support allowlisted sources: canonical customer/channel attributes, immutable audience snapshot fields, campaign constants, safe computed fields, and approved connector lookups. Do not allow arbitrary expression/code execution.
• Provide escaped template interpolation for prompts/greetings/workflow inputs/tool parameters with field-level access controls, maximum lengths, allowed values, normalization, and prompt-injection/data-boundary protections.
• Require explicit behavior for missing/invalid/stale values: safe fallback, omit optional section, take configured workflow edge, or skip recipient with reason. Never fabricate a plausible value.
• Freeze the rendered/personalization input snapshot (or privacy-safe digest plus governed evidence) and agent/workflow/template version per attempt so behavior can be reproduced/audited.
• Add preflight coverage for missing/invalid values, uniqueness/cardinality, sensitive fields, sample rendered outputs across representative segments, and downloadable safe row findings.

Experiments

• Model immutable experiment definition with hypothesis, primary/guardrail metrics, unit of randomization, mutually exclusive variants, allocation, eligibility, start/end/stopping policy, minimum sample guidance, and owner/approval.
• Use deterministic hash-based assignment and persist it before dispatch; a recipient stays in one variant across eligible retries/follow-ups unless the experiment explicitly defines a different unit.
• Support control plus variants referencing immutable campaign/agent/workflow/template/voice/model versions and allowed parameter differences; prevent changing live variants without creating a new experiment/version.
• Support holdout, phased allocation/canary, pause/stop, exclusions, traffic imbalance checks, sample-ratio mismatch alerts, and contamination checks across overlapping experiments.
• Require guardrails for opt-out/complaint, failure, transfer, latency, cost, and safety/eval regressions; stopping an experiment follows campaign pause/cancel semantics and does not silently reassign recipients.

Goals, attribution, and reporting

• Define organization goals/conversion events with stable key, source, timestamp semantics, value/currency, dedupe key, customer/external ID, evidence, eligibility, and versioned attribution policy.
• Accept conversions from QuickVoice terminal/disposition/extracted events and signed API/webhook/integration sources; validate identity, timestamp, currency, deduplication, and source trust.
• Support configurable first/last/linear/position-based or “observed after interaction” attribution, lookback/window, qualifying attempts/touches, and late-event restatement policy; store the applied policy/version and alternatives where feasible.
• Report audience, attempts, connects, outcomes, goal counts/rates/value, attributed conversions/value, cost per outcome/conversion, confidence interval/effect estimate, guardrails, and data-quality warnings by variant, campaign, version, segment, disposition, and time.
• Show absolute counts/denominators and confidence/uncertainty; label analyses as observational where randomization/eligibility/instrumentation is insufficient and never claim causal lift automatically.
• Support privacy-safe exports and scheduled reports using canonical analytics definitions.

API, data, and event implications

• Add personalization schema/version, recipient value snapshot/finding, rendered-config digest, experiment/version/variant/allocation/assignment/exclusion, goal definition/version, conversion event, attribution result/policy, and report snapshot records.
• Expose schema/preflight/preview APIs; experiment draft/validate/start/pause/stop/status; conversion ingest/correct; report/query/export, all paginated, organization-scoped, idempotent, and documented in OpenAPI/SDKs.
• Emit personalization validated/fallback/skipped, experiment assigned/excluded/imbalance/guardrail/stopped, goal/conversion received/deduped/rejected/corrected, attribution computed/restated, and report-generated events with safe dimensions.
• Use event/assignment/conversion IDs and occurrence/ingestion timestamps; analytics tolerates late/duplicate/out-of-order events and keeps revision history.

UX and accessibility

• Mapping/preflight shows field source/type/sensitivity, coverage, invalid/missing counts, fallback behavior, and masked representative previews before start.
• Experiment setup explains unit, allocation, hypothesis, metrics, guardrails, stopping behavior, and immutable differences; highlight unsupported comparisons/provider differences.
• Reporting shows denominators, definitions, data-freshness/completeness, confidence/uncertainty, cost, guardrails, and attribution policy next to results.
• Charts have table/text alternatives, keyboard filtering, accessible names, non-color encodings, exportable underlying data, and responsive layouts.

Security, privacy, compliance, provider, and cost boundaries

• Field-level permissions and purpose/access policies prevent sensitive customer attributes from entering prompts, providers, tools, exports, or analytics unless explicitly authorized.
• Treat all recipient text as data, not instructions; delimit/escape, restrict destinations, redact logs, and honor retention/DSAR/legal hold.
• Experiments cannot weaken consent, DNC/suppression, disclosure, safety, frequency, budget, provider, or regulated-domain controls; prohibited/sensitive traits cannot be used for unfair targeting or high-impact decisions.
• Conversion ingestion requires scoped authentication/signatures, replay protection, schema validation, and rate limits; do not trust client-supplied revenue/identity without configured evidence.
• Surface incremental provider/attempt/model costs and enforce campaign/variant budgets; cost differences are part of guardrail reporting.

Failure and backward compatibility

• Missing/invalid personalization takes the configured fallback/skip edge and records the reason; rendering failure never sends raw template syntax or another recipient's data.
• Duplicate dispatch/retry preserves experiment assignment and attempt-specific snapshot; duplicate conversion events dedupe deterministically.
• Allocation/configuration changes require a new immutable experiment version and never rewrite historical assignment/results.
• Late/corrected conversions restate reports with revision/freshness indicators rather than mutating evidence invisibly.
• Existing campaign variable behavior and basic reports remain available via a compatibility adapter; historical campaigns show “not instrumented” rather than fabricated experiment/conversion metrics.

Dependencies

• [Contacts] Add customer profiles, lists, segments, consent, DNC, timezones, and suppression rules #117 typed customer attributes, audience snapshots, consent/suppression.
• [Campaigns] Add lifecycle controls, pacing, schedules, retries, concurrency, cancellation, and idempotency #120 immutable campaign runs/recipient attempts/idempotency and [Campaigns] Add answering-machine detection, voicemail, dispositions, callbacks, and follow-up journeys #123 normalized outcomes/journeys.
• Canonical event/metric/cost model, experiment/eval platform, connectors/webhooks, and analytics reporting roadmap work.

Out of scope

• Automated causal claims, guaranteed lift, or an opaque “winning variant” without configured statistical evidence.
• Arbitrary code/expression execution in personalization templates.
• Targeting or decisions that violate policy/law or use protected/sensitive traits without an approved lawful design.
• Replacing a CRM/CDP/warehouse as the universal source of truth.

Acceptance criteria

• Every personalized field is typed, source-attributed, permission-checked, escaped/bounded, and has explicit missing/invalid behavior; preflight reports 100% of selected recipients.
• Preview/render cannot fabricate values, leak one recipient to another, execute recipient text as instructions, or expose masked fields to unauthorized users.
• Experiment assignment is deterministic, persisted before dispatch, balanced within configured tolerance, stable across retries, and mutually exclusive according to policy.
• Live variant content is immutable; pause/stop does not reassign recipients or bypass campaign controls.
• Conversion ingestion is authenticated, idempotent, identity/time validated, revision-aware, and tied to versioned attribution policy/evidence.
• Reports reconcile to campaign/attempt/conversion totals, show counts/denominators/cost/guardrails/freshness/uncertainty, and accurately label observational versus randomized evidence.
• Historical/uninstrumented campaigns and current variable/report paths remain backward compatible.

Required tests

• Template/parser/property tests for types, locale formatting, escaping, length/enum constraints, missing/stale values, injection strings, sensitive fields, and cross-recipient isolation.
• Deterministic assignment and statistical tests for allocation, retries, concurrent workers, changed audience order, holdout/exclusions, overlap, imbalance/SRM, and immutable versions.
• Conversion/attribution tests for duplicates, replay, identity mismatch, multiple touches, window boundaries/timezones, late/corrected events, currency/value validation, and policy changes.
• Analytics reconciliation/golden tests for denominators, segments, variants, confidence intervals/effect estimates, guardrails, cost, privacy thresholds, and exports.
• Authorization/security tests for field-level access, consent/DNC bypass, protected traits, webhook signatures, redaction, retention/DSAR/legal hold, audit, and tenant isolation.
• Console end-to-end/accessibility tests for mapping/preflight/preview, experiment setup/control, warnings, report drill-down/table alternatives, keyboard use, and responsive layouts.