# Context

Canonical language for the AI Platform Lead Scoring service. Behavior is specified in `docs/specs/ai-platform-lead-scoring.md`; exact wire shapes are in `contracts/lead-scoring/`. Local checks do not establish client (Omni/EMS) integration, live AI behavior or production readiness.

## Systems and ownership

- **AI Platform:** a shared, stateless-in-business-terms scoring service. It executes rules, calls an AI model, returns the result and stores the run for replay and the Admin Web.
- **Client (currently DotB-Omni):** owns rules, weights, score thresholds, human review, user authorization, lead snapshot construction and CRM writeback. The service has no client-specific code; client data travels in `metadata`.
- **DotB EMS:** CRM system of record for leads.
- **AIHub:** external AI gateway that receives the client's AI key from the `X-AI-Key` header. An AI profile may instead select an OpenAI-compatible endpoint with a server-side key. AIHub's real protocol and behavior are not independently verified.

## Domain terms

- **App / installation:** one client deployment with a stable `app_id` and one backend API key. The service stores only a verifier. Rotation keeps run ownership. Admin Web uses an independent session; issuance and rotation are operator CLI only.
- **Snapshot:** bounded input assembled by the client from a lead and its conversations.
- **Scoring configuration:** rules, `rule_weight` and `ai_weight`, supplied per request by the client.
- **Rule score / AI score / final score:** the deterministic rule result, the model's score, and `clamp(round(rule*rule_weight + ai*ai_weight), 0, 100)`.
- **AI profile:** a service-owned, revisioned configuration (provider, URL, model, timeout, reasoning effort, rubric instructions, prompt switches). Saving creates an inactive revision; activating is a separate step. Each run records the revision used.
- **AI key:** the client's credential for AIHub, sent per request in `X-AI-Key` and held in memory only.
- **Idempotency key:** a client UUID, unique per `(app_id, idempotency_key)`. Same key and body replays the stored result; same key and different body is rejected.
- **Result mode:** `rules_only`, `hybrid` or `rules_only_fallback`; the fallback carries an `error_code`.
- **Metadata:** an opaque client JSON object (max 10KB) stored and returned unchanged.

## Disambiguation

- **Rules and weights** are client policy; **rule execution** is service behavior.
- **Idempotency** prevents duplicate runs for a key; it does not guarantee exactly-once AI invocation.
- **Draft/review_ready** means prepared for review only, not approved or implemented.