Document Type: Specification
Status: Active
Version: v1.1
Authority: Affiliate Brain (Audience Infrastructure Layer)
Applies To: Validation requirements for events written to public.audience_events, including category integrity, consent safety, duplicate protection, and audit logging
Parent: Supabase Event Schema
Last Reviewed: 2026-03-14
Purpose
This document defines the mandatory validation requirements for any event written to:
public.audience_events
Its purpose is to prevent:
• category misuse
• score inflation
• malformed attribution
• consent violations
• structural corruption
No event may enter the system unless it satisfies this contract.
Execution enforcement may later be implemented via SQL function and RLS.
Scope
This specification applies to:
• all audience events written to public.audience_events
• base event-structure validation
• category-specific validation rules
• duplicate protection rules
• illegal state-escalation prevention
• sanity checks
• rejected-event audit logging
This document governs what makes an audience event valid or invalid.
It does not govern:
• live campaign execution
• capital allocation
• Velocity decisions
• audience state model design beyond validation enforcement
• final SQL implementation details beyond the defined validation intent
Those remain governed by Affiliate Brain, HeadOffice, Finance Brain, and related audience infrastructure documents.
Definition / Rules
Base Structure Requirements (All Events)
The following fields must be present and non-empty:
• session_id
• event_type
• event_category
• event_source
Additionally:
• created_at must default to now()
• metadata must be valid JSONB
• event_category must exist in the canonical allowed list
If any are missing, reject the event.
Category-Specific Requirements
Engagement
Must include at least one of:
• content_id in metadata
• page_path in metadata
If event_type = content_view:
Must include:
• duration_seconds or scroll_depth_percent
If duration_seconds < 20 and scroll_depth_percent < 30:
Reject for scoring and log as system event_validation_fail.
Subscription
Must include:
• channel
• consent_recorded = true
If consent_recorded != true:
Reject the event.
If event_type = email_subscribe:
Must include a valid email hash.
Raw email must never be stored in metadata.
Advocacy
Must include:
• platform
• share_type
If event_type = referral_click:
Must include outbound_target.
Likes do not qualify as advocacy.
Retention
Must include:
• prior_state
• new_state
• inactivity_days
• rule_id
If rule_id is not recognized:
Reject the event.
Attribution
Must include:
• session_id
• landing_page
If utm_campaign is present:
• utm_source and utm_medium must also be present
System
Must include:
• validation_rule_id
• validation_result
• source_system
System events may not increment engagement_score.
Duplicate Protection
The system should reject events if all of the following are true:
• same user_id
• same event_type
• same session_id
• within 3 seconds
This prevents accidental double-fire tracking.
Illegal State Escalation Block
Events that attempt to cause any of the following must be rejected at the validation layer:
• direct S0 → S3 jump
• direct S1 → S4 jump
• direct S0 → S5 jump
Sanity Checks
Reject events if:
• event_type length is less than 3
• session_id length is less than 8
• metadata exceeds safe size threshold, recommended maximum 8 KB
• event_category is not in the canonical allowed list
Audit Requirement
Every rejected event must log:
• validation_rule_id
• rejection_reason
• original_payload_snapshot
• source_system
The rejected event must be logged as:
• event_category = system
• event_type = event_validation_fail
Execution Note
This contract is definitional only.
Later implementation may require:
• validate_audience_event() SQL function
• RLS policy requiring validation-pass flag
• optional edge function for pre-validation
Drift Protection
The system must block:
• malformed events entering public.audience_events
• category misuse that inflates engagement or advocacy
• consentless subscription events
• retention changes without rule trace
• duplicate event fires being counted as real behavior
• illegal audience-state jumps
• system events affecting audience growth metrics
Audience event validation must remain strict, auditable, and non-inflationary.
Architectural Intent
Audience Event Validation Contract exists to ensure that Audience Engine measurement remains structurally reliable before any audience-state progression, reporting, or strategic interpretation occurs.
Its role is to prevent corrupted event inputs from distorting engagement, subscription, advocacy, retention, attribution, and system integrity across the MWMS audience infrastructure.
Change Log
Version: v1.1
Date: 2026-03-14
Author: MWMS HeadOffice / Affiliate Brain
Change: Rebuilt page to align with MWMS document standards. Added standardised document header, replaced legacy metadata with compliant structure, introduced Purpose / Scope / Definition / Rules format, normalised validation sections, and preserved the original base requirements, category-specific rules, duplicate protection, audit requirements, and deferred implementation notes.
Version: v1.0
Date: 2026-02-25
Author: Affiliate Brain
Change: Initial creation of Audience Event Validation Contract defining mandatory validation requirements for events written to public.audience_events, including structure requirements, category-specific rules, duplicate protection, illegal state-escalation blocks, sanity checks, and rejected-event audit logging.
END – AUDIENCE EVENT VALIDATION CONTRACT v1.1