dotb_ai-platform/CONTEXT.md

Context

Canonical language for the AI Platform Lead Scoring provider. The approved rebuild and app-auth baseline omni-ai-platform-app-auth revision 2 are implemented and covered by local provider tests. The provider specification docs/specs/ai-platform-lead-scoring.md remains review_ready for cross-service acceptance. Local checks do not establish Omni/EMS integration or production readiness; see docs/contracts/app-auth-provider-handoff.md for evidence and remaining checks. Current implementation is under src/ai_platform/ and apps/web/; historical code and contracts are available in Git history only.

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: default external AI gateway expected to validate/use per-request V-Key and own model access, quota, and provider behavior. An internal, versioned Lead Scoring AI profile may instead select a separate OpenAI-compatible adapter with a server-side key. AIHub's protocol and integration have not yet been independently verified; never infer endpoints, headers, or payloads.

Domain terms

• App / installation: one Omni deployment/environment with a stable app_id; one backend API key shared by its accounts. Provider checks active state and the simple Lead Scoring permission, and stores only a verifier. Rotation keeps run ownership. Admin Web uses an independent session; issuance/rotation is operator CLI only.
• Account: Omni workspace identified by account_id in the request. Omni owns user/account/EMS authorization; AI Platform does not register accounts. (app_id, account_id) distinguishes workspaces across installations.
• 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: light, medium, or heavy in an Omni request denotes the bounded orchestration mode. Separately, the internal versioned Lead Scoring configuration selects the provider, model, prompt and timeout; each run freezes its version. Provider choice is not an Omni request field. Concrete models and AIHub behavior still require verification.
• Scoring run: one provider execution for one app/account context, 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 (app_id, account_id, request_id). Same UUID and same canonical body replays the existing run; same UUID and different body conflicts. A new scoring attempt uses a new UUID. Fingerprint normalization uses the HTTP-validated body serialized as sorted-key compact UTF-8 JSON; generated OpenAPI and fixtures define the input contract.
• Result GET: app-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 carrying app/account/request/run identity and terminal status. Server-side AI_PLATFORM_APP_WEBHOOKS chooses each app's destination and secret. The notification is not the result source of truth; Omni GETs the run. Signature/replay and consumer writeback still require cross-service acceptance.
• 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 app 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.