# Context

Canonical language for the AI Platform Lead Scoring provider. The implementation described here is planned, not verified as working. The provider specification `docs/specs/ai-platform-lead-scoring.md` is a `draft/review_ready`, pending approval.

## Systems and ownership

- **AI Platform:** provider service for bounded AI profiles, rule execution, scoring-run lifecycle, result retrieval, and terminal notification.
- **DotB-Omni / Omni:** customer-facing authority for configured rules and weights, HITL policy and actions, caller-side authorization, lead identity/snapshot construction, and CRM writeback. Omni reads details from the provider after a signed notification.
- **DotB EMS:** CRM system of record for leads.
- **AIHub:** external AI gateway expected to validate/use V-Key and own model access, quota, and provider behavior. Its protocol and integration have not yet been independently verified; never infer endpoints, headers, or payloads.

## Domain terms

- **Tenant:** customer/account boundary used to scope credentials, idempotency keys, and run access. A run lookup must remain inside its authenticated tenant.
- **Tenant key:** service credential used to authenticate a tenant/caller at the provider boundary, subject to final agreed provisioning contract. It is distinct from the raw **V-Key** used for AIHub access. Do not treat the terms as interchangeable.
- **V-Key:** sensitive AIHub credential material. Target rule: keep raw value in memory only for the active execution attempt; never persist, log, trace, or send it to the browser. Source and exact forwarding protocol are unresolved.
- **Canonical snapshot:** bounded input assembled by Omni from the lead and permitted evidence. It is an input snapshot, not an AI Platform-owned CRM record.
- **Scoring configuration:** customer-authored rule/weight and HITL configuration owned by Omni. The provider may consume an immutable version with the request for reproducibility; it does not become the customer configuration authority.
- **AI profile:** provider execution choice `light`, `medium`, or `heavy`. These are three bounded orchestration modes, not confirmed AIHub-native offerings. Concrete models, passes, limits, and timeouts are unresolved.
- **Scoring run:** one provider execution for one tenant, request UUID, subject, snapshot, configuration version, and AI profile. The server-generated run UUID identifies the persisted run.
- **Request UUID / idempotency identity:** client-provided UUID included in the request body, scoped to a tenant. Same UUID and same canonical body replays the existing run; same UUID and different body conflicts. A new scoring attempt uses a new UUID. Exact fingerprint normalization remains contract work.
- **Result GET:** tenant-authenticated read of the authoritative run result. Omni calls it after receiving a signed terminal notification.
- **HITL (human-in-the-loop):** human review workflow and customer actions owned by Omni. The provider does not authorize end users or own the review interface.
- **Terminal notification:** provider-to-Omni signed HMAC webhook indicating a run outcome. It is a notification, not the result source of truth; Omni GETs the run. HMAC envelope, replay window, and retry protocol are unresolved.
- **Recovery:** after interruption of the single-process runtime, terminalize work that cannot continue because its volatile task/V-Key was lost. Recovery is not resumption and does not imply automatic re-execution.
- **Retention:** proposed deletion/redaction of sensitive run material after 90 days. Backup deletion, audit retention, and tenant offboarding behavior need explicit approval.

## Disambiguation

- **Rules and weights** are customer policy owned by Omni; **rule execution** is provider behavior owned by AI Platform.
- **Customer action** means Omni-authorized configuration/review/initiation behavior; an API caller's identity does not establish end-user permission.
- **Webhook delivery state** is separate from scoring-run state. A notification failure does not by itself rewrite a completed scoring result.
- **Idempotency** prevents duplicate admission for a body UUID; it does not guarantee exactly-once AIHub invocation or webhook delivery.
- **Draft/review_ready** means prepared for stakeholder review only. It does not mean approved, released, or implemented.