Audit Views Documentation
Status: ✅ PRODUCTION READYPhase: 1.5
Last Updated: 2025-01-XX
Overview
This document defines the six audit artifact views that provide audit-grade traceability for commission allocations, agent payouts, business lifecycle events, headcount changes, and churn analysis. All views are read-only projections and do not modify any existing Stage tables or semantic views. Key Principles:- Additive Only: No modifications to Phase 0 artifacts or existing stage tables/views
- Read-Only: All views are projections only (no INSERT/UPDATE/DELETE)
- Tenant Isolation:
tenant_idmust be included in ALL joins - Traceability: Money/allocation views MUST have
stage3_component_id; headcount views have OPTIONALstage3_component_ids - NUMERIC Safety: All money fields use
NUMERIC(not FLOAT64)
View Inventory
stage1_headcount_by_business_period- Performance helper view (pre-aggregates employee counts)audit_commission_summary- Component reconciliation summary (money/allocation - REQUIRES stage3_component_id)audit_agent_payout_trace- Detailed trace of component allocations to Stage1 rows (money/allocation - REQUIRES stage3_component_id)audit_business_lifecycle- Business lifecycle events with commission impact (lifecycle - OPTIONAL stage3_component_ids)audit_employee_headcount_timeline- Employee count changes over time (headcount-only - OPTIONAL stage3_component_ids)audit_business_churn_events- Churned businesses with peak snapshot and commission impact (churn - OPTIONAL stage3_component_ids)audit_business_churn_agent_impact- Churn events tied to affected agents (money/allocation - REQUIRES stage3_component_id)
Definitions
Attrition
Definition: Within-company employee reduction while the company remains active. Characteristics:- Company remains active (
employee_count > 0) - Employee count decreased from previous period
- Threshold:
pct_change <= -0.15ANDprior_employee_count >= 20(minimum base threshold to avoid noise)
MINOR_CHANGE ⚠️
Churn
Definition: Business disappears or goes to 0 employees (company no longer active). Types:-
FULL_CHURN:- Business went from >0 employees to 0 employees
- Still appears in
stage1_snapshotswith 0 count churn_confidence:HIGH
-
DISAPPEARED:- Business no longer appears in
stage1_snapshotsafterlast_active_period - Absent for >= grace_window consecutive expected periods (see Cadence Inference below)
churn_confidence:HIGH(if >= grace_window),MEDIUM(if < grace_window but > 1 period),LOW(single period or unknown cadence)
- Business no longer appears in
Growth
Definition: Within-company employee increase while the company remains active. Characteristics:- Company remains active (
employee_count > 0) - Employee count increased from previous period
- Threshold:
pct_change >= 0.15ANDprior_employee_count >= 20(minimum base threshold to avoid noise)
MINOR_CHANGE ⚠️
MINOR_CHANGE
Definition: Small-base or small-percentage employee changes that don’t meet growth/attrition thresholds. Characteristics:ABS(employee_change) > 0- Either
prior_employee_count < 20(small base) ORABS(pct_change) < 0.15(small percentage change)
Cadence Inference
Purpose
ForDISAPPEARED churn detection, we need to determine the “grace window” (number of consecutive absent periods required to classify as churn). This depends on the tenant’s payroll cadence (weekly, bi-weekly, monthly, etc.).
Method
-
Calculate Period Gaps: For each tenant, calculate
diff_daysbetween consecutiveperiod_labelvalues instage1_headcount_by_business_period. -
Classify Cadence: Use
MODE(diff_days)per tenant to determine the most common period gap:diff_days ≈ 7: WEEKLY → grace_window = 6 periodsdiff_days ≈ 14: BIWEEKLY → grace_window = 4 periodsdiff_days ≈ 30: MONTHLY → grace_window = 2 periodsdiff_days ≈ 60: BIMONTHLY → grace_window = 2 periods- Other/Unknown: UNKNOWN → grace_window = 2 periods (default),
churn_confidence=LOW
-
Apply Grace Window: A business is considered
DISAPPEAREDif it’s absent for >= grace_window consecutive expected periods.
Implementation
Seeaudit_business_churn_events.sql for the full implementation using APPROX_TOP_COUNT to find the mode of diff_days per tenant.
Churn Confidence
Thechurn_confidence field in audit_business_churn_events indicates the reliability of churn detection:
HIGH:FULL_CHURN(employee_count = 0), ORDISAPPEAREDwith >= grace_window periods (known cadence)
MEDIUM:DISAPPEAREDwith < grace_window but > 1 period
LOW:- Single period absence (may be data gap), OR
- Unknown cadence (cannot determine expected period frequency)
Assumptions
1. Employee Count Authority
- Authoritative Source:
COUNT(DISTINCT member_id)fromstage1_snapshots - Helper View:
stage1_headcount_by_business_periodpre-aggregates this calculation for performance - DO NOT USE:
absorbed_countfromstage3_snapshots(it’s a commission calculation artifact, not actual headcount)
2. Growth/Attrition Thresholds
- Minimum Base Employee Count:
prior_employee_count >= 20(to avoid noise from small businesses) - Minimum Percentage Change:
ABS(pct_change) >= 0.15(15%) - Classification: Changes that don’t meet both thresholds are classified as
MINOR_CHANGE
3. Churn Detection
- FULL_CHURN:
employee_count = 0in current period ANDemployee_count > 0in previous period - DISAPPEARED: Business appears in period N but is absent for >= grace_window consecutive expected periods
- Grace Window: Determined by cadence inference (see Cadence Inference section above)
- churn_confidence: Indicates reliability (HIGH/MEDIUM/LOW)
4. Commission Impact
- All commission impact calculations are read-only projections from authoritative
allocated_commission_amount_rawvalues inview_commission_traceability - No new payout logic is introduced
- NULL Safety:
loss_amount = COALESCE(commission_at_peak, 0) - COALESCE(commission_at_churn, 0)(positive = loss)
5. Peak Snapshot
- Peak employee count and peak period are calculated as
MAXover all historical periods for a business, regardless of current status
6. Agent Role Derivation
- Agent roles (DIRECT/UPLINE/OVERRIDE) are derived from joins to
stage1_snapshotsanddim_agent_hierarchy - CRITICAL: Joins to
stage1_snapshotsusingstage1_row_idMUST includetenant_id: - If role cannot be determined, it is marked as
UNKNOWN
7. Traceability Requirements
- Money/Allocation Views (#2, #3, #7): MUST have
stage3_component_id(REQUIRED)audit_commission_summaryaudit_agent_payout_traceaudit_business_churn_agent_impact
- Headcount-Only View (#5):
stage3_component_idis OPTIONAL (may be NULL)audit_employee_headcount_timeline
- Lifecycle/Churn Views (#4, #6): Include
stage3_component_idswhen commission exists, NULL/empty array otherwiseaudit_business_lifecycleaudit_business_churn_events
Validation Methods
Employee Count Validation
Commission Impact Validation
Churn Event Count Validation
Stage3 Component ID Traceability
Tenant Isolation Validation
Deployment Order
- First:
stage1_headcount_by_business_period.sql(helper view - required by other views) - Second:
audit_business_churn_events.sql(required by churn_agent_impact) - Third:
audit_business_churn_agent_impact.sql(depends on churn_events) - Independent:
audit_commission_summary.sql,audit_agent_payout_trace.sql,audit_business_lifecycle.sql,audit_employee_headcount_timeline.sql(can be deployed in any order)
Notes
- These views are additive - they do not modify Phase 0 or Phase 1 code
- Views can be deployed independently (no migration dependencies)
- Views are optimized for audit queries (not real-time UI filtering)
- Employee count is authoritative at Stage1 level (
COUNT(DISTINCT member_id)) - Commission impact is read-only projection from authoritative values (no new payout logic)
- All joins include
tenant_idfor tenant isolation stage1_row_idjoins MUST includetenant_id:ON v.tenant_id = s.tenant_id AND v.stage1_row_id = s.stage1_row_id
Validation Queries
These SQL queries validate data quality, tenant isolation, traceability completeness, and reconciliation accuracy. Run these periodically to ensure audit-grade integrity.A) Cross-Tenant Leakage Check
Purpose: Verify tenant isolation - no data from one tenant should appear in another tenant’s results. Expected Result: 0 rows (any rows indicate tenant isolation failure)B) Money View Traceability Completeness
Purpose: Verify that money/allocation views havestage3_component_id where required.
Expected Result: 0 rows (any rows indicate missing traceability)
C) Headcount Reconciliation
Purpose: Verify that headcount counts match authoritative Stage1 source (COUNT(DISTINCT member_id)).
Expected Result: 0 rows (any rows indicate reconciliation failure)
D) Churn View Determinism
Purpose: Verify that churn views use deterministic as-of dates (no CURRENT_DATE()). Expected Result: Query should run successfully and show asof_period values (not CURRENT_DATE())E) Commission Reconciliation
Purpose: Verify that component source totals reconcile with allocated totals (within tolerance). Expected Result: All rows should havereconciliation_status = 'RECONCILED' or abs_diff <= 0.01
F) Early-History Tenant Churn Suppression
Purpose: Document and verify that tenants with insufficient timeline depth (< grace_window periods) do not emit false DISAPPEARED churn events. Expected Behavior: Tenants with < grace_window periods should have LOW confidence or no DISAPPEARED events.Validation Queries (Phase 1.5)
These queries validate theaudit_business_churn_agent_impact view specifically, ensuring correctness, tenant isolation, role derivation, and NUMERIC-only math safety.