---
name: Handoff Protocol - mql-enrichment-service
description: Structured envelope passed between mql-enrichment-service -> mql-router -> sdr-handoff-helper. Schema versioned in kit/contracts/. Owner: this RevOps-AI team.
type: cross-platform-artifact
layer: L7-concern
Owner: RevOps-AI eng team
---

# Handoff Protocol - mql-enrichment-service

- **Last reviewed:** 2026-04-25
- **Review cadence:** quarterly + on schema bump
- **Status:** exists-mature

## What this means here

When one platform completes its part of the workflow, the next platform receives a structured envelope with state, history, and confidence. Without a protocol, downstream platforms would either re-derive state (expensive, redundant) or rely on warehouse polling (slow, prone to race conditions).

## Implementation

- **Envelope schema:** `kit/contracts/handoff-envelope-schema.json` (version `2.0.0`)
- **Transport:** {{queue_or_messagebus}} topics, one per stage transition:
  - `enrichment-complete` topic: from mql-enrichment-service to mql-router
  - `assignment-complete` topic: from mql-router to sdr-handoff-helper
- **Delivery semantics:** at-least-once; consumers idempotent on `mql_id` + envelope version
- **Schema enforcement:** producers validate against schema before publish; consumers validate on consume; mismatch routes to dead-letter queue with alert

## Envelope schema (summary)

```
{
  "envelope_version": "2.0.0",
  "stage_transition": "enrichment-complete | assignment-complete",
  "mql_id": "uuid",
  "tenant_id": "string",
  "trace_id": "uuid",
  "produced_at": "ISO-8601",
  "produced_by": "platform name",
  "state": {
    "enrichment_tier": "...",
    "consent_check_result": "...",
    "intent_score": 0.0,
    ...
  },
  "history": [
    { "stage": "...", "timestamp": "...", "result": "..." }
  ],
  "confidence": 0.0,
  "context_pointers": {
    "shared_memory_row": "revops.mql_facts/{mql_id}",
    "telemetry_request_id": "uuid"
  }
}
```

Full schema lives at `kit/contracts/handoff-envelope-schema.json`.

## Participants

| Platform | Produces envelope | Consumes envelope |
|----------|------------------|------------------|
| mql-enrichment-service | yes (enrichment-complete) | no |
| mql-router | yes (assignment-complete) | yes (enrichment-complete) |
| sdr-handoff-helper | no (terminal) | yes (assignment-complete) |

## Idempotency

Consumers handle duplicate envelopes gracefully (at-least-once delivery requirement):

- mql-router: keys assignment by `mql_id` + envelope `produced_at`; duplicate within a 5-minute window is ignored; duplicate after the window triggers re-routing if state has changed
- sdr-handoff-helper: helper card render is read-side; duplicate envelope causes a re-render with no state change

## Last verified live

2026-04-25: synthetic envelope through all three stages. Latencies: enrichment-complete -> mql-router consume in 280ms (p50); assignment-complete -> sdr-handoff-helper consume in 190ms (p50). Schema validation passed at every boundary.

## Inheritance and dependencies

Inherits from: {{cutting_edge_saas_company}} corporate eventing infrastructure ({{queue_or_messagebus}}).

Consumed by: all three L5 dossiers in this instance.

## Cross-references inside this instance

- `cross-platform/L7-glue.md`
- `kit/contracts/handoff-envelope-schema.json` - the schema
- `runbooks/handoff-dead-letter-recovery.md` - what to do when validation fails at consumer
