Document Type: Specification
Status: Active
Version: v1.1
Authority: Affiliate Brain (Audience Automation-Ready Layer)
Applies To: Controlled derivation of public.audience_state from validated audience events, including audit logging, fail-safe behavior, and service-role write discipline
Parent: Audience Event Validation Contract
Last Reviewed: 2026-03-14
Purpose
This document defines the controlled process that derives current audience state from raw audience events.
This job is the only approved mechanism permitted to write to:
public.audience_state
Its purpose is to ensure:
• consistent state calculation
• audit traceability
• prevention of manual tampering
• compatibility with RLS and service-role execution
Execution remains deferred.
Scope
This specification applies to:
• derivation of audience state from raw event logs
• filtering and deduplication of eligible events
• audience-state calculation rules
• audit logging of state changes
• fail-safe handling for invalid or suspicious event conditions
• controlled write permissions for public.audience_state
This document defines how the derivation job must behave.
It does not govern:
• raw event validation rules themselves
• audience-state scoring weights themselves
• RLS implementation details
• cron configuration details
• edge-function deployment details
• capital allocation or Velocity behavior
Those remain governed by related audience infrastructure documents.
Definition / Rules
Inputs
Source table:
public.audience_events
Required filters:
• only validated events (validation_pass)
• only canonical event_category and event_type values
• deduplicated events according to contract rules
Derived table:
public.audience_state
Outputs
For each user_id, the job may write:
• current_state
• state_updated_at
• engagement_score
• last_event_type
• metadata, optional aggregated output
If user_id is null, no row is written to audience_state.
Anonymous engagement is tracked only at event level.
Job Frequency (Recommended)
Two execution modes are allowed.
Mode A – Scheduled
Preferred for simplicity.
Recommended frequency:
• every 15 minutes
or
• hourly during early build
Mode B – Trigger-Based
Advanced mode.
• run on insert of audience_events
• must include hard dedupe guardrails
Default recommendation:
Mode A – Scheduled
Derivation Algorithm (Canon)
For each user_id, the derivation job must:
- Pull events within the lookback window
• default: last 120 days - Apply validation rules
• discard invalid or malformed events - Apply dedupe
• sameuser_id+event_type+session_idwithin 3 seconds → keep first only - Calculate
engagement_score
• use canonical weights from Audience State Transition Rules
• ignore unqualifiedcontent_viewevents - Determine state transitions
• apply ordered checks:S0 → S1 → S2 → S3 → S4 → S5
• no skipping allowed
• apply downgrade rules last - Write result to
audience_state
• upsert byuser_id
• update only if state changed orengagement_scorechanged orlast_event_typechanged
State Change Audit Requirements
Every time audience_state changes, the job must log an event by inserting into audience_events.
Required values:
• event_category = system
• event_type = state_change_logged
Metadata must include:
• prior_state
• new_state
• rule_trigger, event type or retention rule_id
• derived_at
• derived_by, job identifier
No silent state changes are permitted.
Fail-Safe Rules
The job must stop and log validation_fail if any of the following occur:
• unknown event_category
• state jump detected
• consent_recorded missing for subscription events
• abnormal event-volume spike per user_id, indicating possible spam
When a fail-safe trigger occurs:
• do not update audience_state for the affected user_id
• log a system event with the rejection reason
Security Model
Only service_role may execute derivation writes.
anon and authenticated roles may not update audience_state.
RLS must remain enabled.
Performance Notes
Recommended indexes:
• audience_events(user_id, created_at desc)
• audience_events(session_id)
• audience_state(user_id)
The lookback window should be adjustable.
Activation Status
Current status:
Spec defined
SQL function and scheduler not yet implemented
Next Layers (Not Included Here)
Later implementation may include:
• SQL Function: derive_audience_state(user_uuid)
• SQL Function: run_audience_derivation_batch()
• scheduler configuration, Supabase cron or Edge scheduled function
• observability layer, derivation job logs and failure dashboard
Drift Protection
The system must prevent:
• manual writes to public.audience_state
• silent state changes without audit logging
• invalid or malformed events influencing state
• state skipping across progression levels
• duplicate event bursts inflating audience-state changes
• non-service roles mutating derived audience state
Audience state must remain derived, auditable, and tamper-resistant.
Architectural Intent
Audience State Derivation Job Spec exists to ensure that audience-state progression inside MWMS is not manually interpreted or loosely updated.
Its role is to provide a controlled, auditable, rule-based mechanism for converting validated behavior into derived audience state while preserving security, traceability, and anti-inflation integrity.
Change Log
Version: v1.1
Date: 2026-03-14
Author: MWMS HeadOffice / Affiliate Brain
Change: Rebuilt page to align with MWMS document standards. Removed duplicated title text, added standardised document header, replaced legacy metadata with compliant structure, introduced Purpose / Scope / Definition / Rules format, normalised derivation and audit sections, and preserved the original derivation-job logic, fail-safe rules, security model, and deferred implementation status.
Version: v1.0
Date: 2026-02-25
Author: Affiliate Brain
Change: Initial creation of Audience State Derivation Job Spec defining the controlled process for deriving public.audience_state from validated audience events, including inputs, outputs, derivation algorithm, audit requirements, fail-safe rules, security model, and deferred next-layer implementation notes.
END – AUDIENCE STATE DERIVATION JOB SPEC v1.1