---
name: L3 Framework Contract - mql-enrichment-service
description: Technical contract every component of mql-enrichment-service implements. Eval methodology and thresholds, per-call cost ceiling, telemetry schema, auth model, and four-layer guardrail architecture.
type: layer-artifact
layer: L3
populated_from: Q5, Q4 (red lines drive guardrails), Q9 (compliance shapes telemetry and auth)
Owner: RevOps-AI eng lead, with Platform Engineering signoff on auth model and telemetry destination
---

# L3 Framework Contract - mql-enrichment-service

- **Last reviewed:** 2026-04-12 (after Q1 quarterly eval refresh)
- **Review cadence:** quarterly + on every model bump + on every cost ceiling breach
- **Status:** active

## Maturity self-assessment

| Aspect | State | Evidence |
|--------|-------|----------|
| Eval methodology specified | mature | Hybrid (LLM-judge + 10% human review); dataset 800 examples curated; refreshed 2026-04-12 |
| Eval thresholds quantified | mature | Faithfulness >= 0.92, fluency >= 0.85 (low weight; structured output), human-pass >= 0.95 |
| Per-call cost ceiling set | mature | $0.08 per MQL enriched; current p90 $0.052 |
| Telemetry schema defined | mature | Reproducibility quadruple + 5 required fields; emits to {{observability_platform}} |
| Auth model decided | mature | tenant-scoped-jwt; rotation 90 days; verified 2026-04-19 |
| Guardrail layering defined | mature | Four layers; each enforces specific L2 red lines; trips logged with type and tier |

## Eval methodology

- **Methodology:** `hybrid` - LLM-judge for enrichment-correctness on 800 curated examples + 10% human-review per quarter
- **Dataset source:** extracted from production logs 2025-09 to 2025-12, redacted via `{{platform_team_name}}/ai-kit/redaction-pipeline`; SDR-validated as gold-standard quarterly
- **Dataset size:** 800 examples (200 per market segment: SMB, MM, ENT, STRATEGIC)
- **Refresh cadence:** quarterly + on every model bump
- **Score thresholds for ship:** faithfulness >= 0.92, fluency >= 0.85, human-pass >= 0.95
- **Latest run:** 2026-04-12; faithfulness 0.94, fluency 0.89, human-pass 0.97 (all met)

## Per-call cost ceiling

- **Ceiling:** $0.08 per MQL enriched
- **Method:** aggregate token cost across all model calls in one enrichment invocation; tools-call costs (warehouse lookups, consent service calls) included; data-egress not included (negligible)
- **Action on breach:** log + soft-fail + alert RevOps-Ops oncall; second consecutive breach within an hour hard-fails the call and alerts RevOps-AI eng lead
- **Override path:** `COST-EXTEND-{NNNN}` Linear ticket signed by RevOps-AI eng lead; valid 7 days; logged in `runbooks/cost-extend.md`
- **Current p90 cost:** $0.052 (well under ceiling); p99 $0.071 (under ceiling)
- **Recent breaches:** 2026-03-14 (one breach; root cause: prompt regression; reverted within 4 hours)

## Telemetry schema

Every component invocation emits, at minimum, the **reproducibility quadruple**:

- `model_version` - exact model identifier from `{{platform_team_name}}/ai-kit/models.yaml`
- `prompt_version` - SHA-256 hash of the prompt template; resolves to `kit/prompts/enrichment-{tier}.md@{hash}`
- `tools_version` - identifier for the tool set, including each tool's version (warehouse-lookup, consent-service, signal-scorer)
- `data_snapshot_version` - identifier for `revops.mql_facts` snapshot at call time

Plus required fields:

- `request_id` - unique per invocation (UUID v7 for time-orderability)
- `tenant_id` - mandatory (multi-tenant; GDPR / SOC 2 obligation)
- `latency_ttfb_ms` and `latency_total_ms`
- `token_input` and `token_output`
- `cost_estimate_usd` - computed against the cost ceiling
- `quality_signal` - eval score, SDR-explicit-feedback, SDR-implicit-engagement, or null
- `guardrail_trips` - list of guardrail layer + tier if any
- `enrichment_source_per_field` - source attribution per enrichment field
- `consent_check_result` - `granted`, `revoked`, `unknown`; absent in unenriched records

**Telemetry destination:** {{observability_platform}}, log group `revops-ai-mql-enrichment`, retention 90 days operational + 7 years SOC 2 audit trail.

**Schema enforcement:** `{{platform_team_name}}/ai-kit/telemetry/schema-validator` rejects writes that do not match; rejection at write time prevents schema drift.

## Auth model

- **Model:** `tenant-scoped-jwt`
- **Carrier:** bearer JWT in `Authorization` header; signed by {{idp_name}}
- **Tenant scoping:** `tenant_id` claim mandatory; mismatched claim hard-rejects at the API gateway
- **Token issuance:** {{idp_name}} via standard {{cutting_edge_saas_company}} workforce SSO + service-account flow for inter-pod calls
- **Token rotation:** 90 days for service accounts; SSO sessions per {{cutting_edge_saas_company}} corporate policy
- **Anonymous calls:** rejected at the API gateway; no fallback path

Verified 2026-04-19 in cross-tenant isolation drill: cross-tenant call attempt with valid JWT for tenant A targeting tenant B's queue rejected at API gateway in 12ms; logged for SOC 2 audit trail.

## Guardrail layering

The four layers, each enforcing specific L2 red lines.

| Layer | Purpose | Implementation for `mql-enrichment-service` |
|-------|---------|---------------------------------------------|
| **Input** | Reject obviously bad inputs before model call | (a) Consent check via `consent-service` API (Red Line 1); revoked = no-enrichment record; (b) PII presence check (`pii-detector`); PII outside tenant boundary = block + alert; (c) MQL freshness check; > 24h old in queue = soft-fail with retry |
| **Prompt** | System prompt content that sets red lines for the model | Prompt template includes explicit "never enrich without checking consent first" and "respect SDR manual edits" clauses; template hash in `prompt_version` telemetry |
| **Output** | Inspect output before returning to caller | (a) Schema validation against `kit/contracts/enrichment-record-schema.json`; (b) SDR-edit-respect check (Red Line 2); (c) staleness check on each field's `data_snapshot_date` (Red Line 3) |
| **Post-hoc** | Async / batch checks on logged outputs | Daily audit job samples 5% of records; checks consent revocation propagation, PII boundary integrity, staleness rate, cost ceiling adherence; fires {{alerting_destination}} on any threshold breach |

Output that trips a guardrail is rejected (or annotated as no-enrichment for revoked-consent), not silently fixed. Each trip is logged with layer + tier in `guardrail_trips` telemetry.

## Reproducibility pin (V1 ship pins)

- Model: `{{model_family}}-{{model_version}}` (mirrored from `{{platform_team_name}}/ai-kit/models.yaml`)
- Prompt template version: `enrichment-tier-1@{hash}`, `enrichment-tier-2@{hash}`, `enrichment-tier-3@{hash}` per tier
- Tool set version: `warehouse-lookup@v2.4.1`, `consent-service@v1.7.0`, `signal-scorer@v3.0.2`
- Eval dataset snapshot: `revops-mql-eval-2026-Q1@{hash}`

Bumping any pin invalidates the eval baseline; re-run eval against the new pin before shipping. Last bump: model bump 2026-03-22 (sonnet-4-5 -> sonnet-4-6); eval re-run with pass.

## Inheritance and dependencies

This L3 inherits from: `policies/strategy.md` (L0 primary metric drives ship thresholds), `policies/philosophy.md` (L2 red lines drive guardrail layering), {{cutting_edge_saas_company}} corporate AI policy on auth.

This L3 is inherited by: every L5 instance dossier (each implements this contract); the L4 platform kit mirrors `{{platform_team_name}}/ai-kit` which provides the implementation pieces.

## Cross-references inside this instance

- `policies/philosophy.md` (L2) - red lines this contract enforces
- `kit/contracts/enrichment-record-schema.json` (L4) - machine-readable record schema
- `kit/PLATFORM-KIT.md` (L4) - the kit-mirror posture and components
- `cross-platform/consent-flow.md` - consent-check implementation referenced by Input guardrail
- `cross-platform/alerting-fabric.md` - guardrail trips route here
- `decisions/ADR-0003-consent-flow-integration.md` - decision record for consent posture
