Skip to main content

​
Phase 1.4 Deliverable C: Effective-Dating Behavior Confirmation

​
Runbook Guidance (Quoted)

From docs/runbooks/phase1_3_prod_population.md:131, 151: 
"effective_start_date": "2024-01-01",

- [ ] `effective_start_date` is set to earliest period (e.g., `2024-01-01`)
Policy: Use effective_start_date = "2024-01-01" for PEPM mappings because identity resolution is effective-dated but does not change payout math; mappings must apply historically.

​
API Logic (Quoted)

From api/routes/admin_identity.py:179-222: The endpoint accepts effective_start_date and effective_end_date from the request body without modification. The validation happens in api/bigquery/admin_identity_queries.py. From api/bigquery/admin_identity_queries.py:352-358: 
# Check for overlaps
has_overlap, error_msg = check_overlap_pepm_map(
    tenant_id, pepm_agent_name_norm, pepm_business_name_norm,
    effective_start_date, effective_end_date
)
if has_overlap:
    raise ValueError(error_msg)
Overlap Check Logic (from api/bigquery/admin_identity_queries.py:78-136): The overlap check uses end-exclusive window logic:
  • Window is active when: effective_start_date <= as_of_date AND (effective_end_date IS NULL OR as_of_date < effective_end_date)
  • NULL effective_end_date means “currently active”
  • Overlap detection checks for any existing active rows with overlapping windows
Current Row Determination:
  • Rows are identified by override_id (stable UUID)
  • No exclude_override_id parameter in check_overlap_pepm_map (unlike check_overlap_identity_admin)
  • This means overlap checks apply to ALL active rows for the same (pepm_agent_name_norm, pepm_business_name_norm) pair

​
Confirmation Statement

Effective Start Date Policy: Use "2024-01-01" as effective_start_date for all initial PEPM mappings. This ensures:
  1. Historical coverage: mappings apply to all periods from 2024-01-01 forward
  2. No payout math changes: identity resolution is metadata-only
  3. Append-only semantics: close rows via effective_end_date only, never delete
Validation: The API enforces end-exclusive overlap checks at write time. If an overlapping window exists, the API returns 400 Bad Request with error message “Overlapping effective date window detected”.