# Lead qualification workflow blueprint

## Trigger and termination

- Trigger: `{event_id, person_key, source, permission_state, received_at}`.
- Success: qualification and deterministic assignment recorded with an owned destination.
- Stop: invalid source/permission, unresolved identity conflict, revoked criteria version or owner-issued stop.

## State model

`received -> validating -> duplicate_review | extracting -> qualifying -> assignment -> review | assigned`

Terminal alternatives: `rejected_source`, `stopped`, `superseded`. Corrections create a new evaluation linked to the prior one.

## Data contract

Keep eligibility, fit, stated need, engagement and ownership as separate objects. Every fact has `{value, source_id, observed_at, freshness_status}`. Extracted text also has `{source_span, extractor_version, confidence_or_abstain}`. Result has `{criteria_version, matched_rules, unknowns, reason_codes}`.

## Ordered steps and actors

1. **Trigger:** receive the lead event.
2. **Code:** deduplicate person/account/open records and validate provenance.
3. **AI (bounded):** extract allowed fields from approved text or abstain.
4. **Code:** apply eligibility and fit rules.
5. **Code:** apply territory, account, queue and capacity rules.
6. **Human:** resolve conflicts, ambiguity and correction requests.
7. **Human:** choose external and commercial next action.
8. **Code:** record final owned route and evidence packet.

## Idempotency, retry and rollback

- Keys: `capture:{event_id}`, `evaluation:{canonical_record_id}:{criteria_version}:{input_hash}`, `assignment:{evaluation_id}:{assignment_version}`.
- Retry enrichment/reads with bounded backoff; preserve unavailable rather than defaulting.
- Before retrying an assignment write, read the destination system by effect ID.
- Rollback reassigns through a corrective event; do not delete the original route.

## Permissions and data handling

Allow only approved source fields. Minimize retention and access. Do not place sensitive or undeclared attributes into model prompts, criteria, logs or test fixtures. Keep external communication outside this workflow unless separately approved.

## Exception routes

- Duplicate/conflicting identity -> record stewardship.
- Missing or stale source -> source owner.
- Extraction abstention -> qualification review.
- No territory/owner match -> default owned queue.
- Criteria dispute -> revenue-operations owner.
- No exception owner -> safe stop.

## Acceptance tests

1. Duplicate capture creates one evaluation.
2. Missing fit field remains unknown and does not subtract points.
3. Conflicting sources show both values and block automatic route where policy says so.
4. Unsupported free text returns abstain with its source span.
5. Qualification and assignment rules remain distinct in the record.
6. No assignment match reaches the default owned queue.
7. Retry does not create a second assignment effect.
8. Criteria correction preserves and links the prior evaluation.

## Audit record

Retain source events, canonical record decision, input/rule/model versions, extracted spans, unknowns, matched rules, assignment result, reviewers, corrections, retries and external effect IDs.