# AGM Canonical Data Contract Specification

Date: 2026-04-18  
Version: 1.0.0  
Owner: Data Integration Lead

## Purpose
Define canonical entities and field contracts used across CRM ingestion, command-center APIs, SLA control flows, and project governance logs.

## Contract Governance Rules
- Contract versions are semantic: MAJOR.MINOR.PATCH.
- Breaking field changes require MAJOR increment and architecture approval.
- New optional fields require MINOR increment.
- Bugfix or formatting-only corrections require PATCH increment.

## Entity: LeadRecord
Canonical key: `domain + contact_email`

Required fields:
- captured_at: ISO-8601 timestamp
- company_name: non-empty string
- domain: normalized domain string
- contact_email: lowercase email string
- lead_score: integer
- lead_tier: enum `Hot|Warm|Cold`
- recommended_service: non-empty string
- lead_owner: string (empty allowed during intake, required before handoff)
- sla_due_at: ISO-8601 timestamp
- status: enum `New|Contacted|Qualified|Disqualified|Converted`

Optional fields:
- contact_phone
- source_table
- match_keywords
- last_activity_at

Primary source:
- `data/offpage/live_lead_intelligence.csv`

API surfaces:
- `api/lead-intelligence.php`
- `api/lead-intelligence-update.php`
- `api/lead-conversion.php`

## Entity: SLAEvent
Canonical key: `domain + contact_email + sla_due_at`

Required fields:
- event_key: deterministic concatenation key
- company_name
- domain
- contact_email
- lead_owner
- sla_due_at
- sla_status: enum `On Track|Due Soon|Breached|Not Set|Invalid`
- escalation_dispatched: boolean
- escalation_acknowledged: boolean

Optional fields:
- escalation_dispatched_at
- escalation_acknowledged_at
- escalation_acknowledged_by
- escalation_ack_note

Primary sources:
- `data/offpage/sla_escalation_dispatch_log.csv`
- `data/offpage/sla_escalation_ack_log.csv`

API surfaces:
- `api/msp-sla-alerts.php`
- `api/dispatch-sla-escalations.php`
- `api/acknowledge-sla-escalation.php`

## Entity: ProjectRecord
Canonical key: `project_id`

Required fields:
- project_id
- status: enum `Kickoff Planning|Active Delivery|Completed|On Hold`
- conversion_stage
- kickoff_owner
- next_action_due
- updated_at

Optional fields:
- source_lead_domain
- source_contact_email
- project_name
- service_line

Primary source:
- `data/offpage/project_pipeline.csv`

API surfaces:
- `api/project-pipeline.php`
- `api/project-pipeline-update.php`

## Entity: WorkflowAuditEvent
Canonical key: `audit_id`

Required fields:
- audit_id
- changed_at
- changed_by
- change_source
- project_id

Optional fields by workflow:
- before_status / after_status
- before_conversion_stage / after_conversion_stage
- before_next_action_due / after_next_action_due
- before_kickoff_owner / after_kickoff_owner
- sdlc_sync_action

Primary source:
- `data/offpage/project_pipeline_audit_log.csv`

API surfaces:
- `api/project-pipeline-audit.php`

## Entity: MilestoneRecord
Canonical key: `project_id + milestone_code`

Required fields:
- project_id
- milestone_code
- milestone_name
- status: enum `Planned|In Progress|Blocked|Completed`
- due_at
- owner
- updated_at

Optional fields:
- source
- note

Primary source:
- `data/offpage/sdlc_project_milestones.csv`

API surfaces:
- `api/sdlc-governance.php`
- `api/sdlc-milestone-update.php`

## Field Mapping: CRM to Command Center LeadRecord
- CRM search/business name -> company_name
- CRM website/domain -> domain
- CRM email -> contact_email
- CRM phone -> contact_phone
- CRM source table -> source_table
- CRM keyword hit list -> match_keywords
- CRM score -> lead_score
- CRM tier -> lead_tier
- Command center owner assignment -> lead_owner
- Command center SLA due calculator -> sla_due_at
- Command center lifecycle state -> status

## Validation Rules
- domain must be lowercase and trimmed.
- contact_email must be lowercase and trimmed.
- lead_score must be integer in range 0-100.
- sla_due_at and captured_at must parse to valid timestamps.
- status and tier must match defined enums.

## Contract Version Baseline
- Current baseline version: 1.0.0
- Effective date: 2026-04-18