# Customer onboarding workflow blueprint

## Trigger and termination

- Trigger: accepted handoff event `{event_id, customer_id, agreement_id, handoff_version}`.
- Success: steady-state packet accepted with every required milestone evidenced and every open item owned.
- Stop: revoked authority, disputed scope, invalid data purpose, unrecoverable identity conflict or owner-issued stop.

## State model

`received -> validating -> returned | planning -> awaiting_plan_approval -> active -> blocked | awaiting_milestone_acceptance -> awaiting_transfer_acceptance -> complete`

Terminal alternatives: `stopped`, `superseded`. Rejections create new events; they do not erase prior state.

## Data contract

Required: case/customer/agreement IDs, source version, outcome, scope/exclusions, stakeholders, owners, dependencies, milestone evidence contracts, data fields with purpose/access/retention, acceptance authority. Generated summaries store source record IDs and spans.

## Ordered steps and actors

1. **Trigger:** receive accepted handoff.
2. **Code:** deduplicate by event ID and case key; validate schema and ownership.
3. **Code:** return named gaps or create the milestone draft.
4. **AI (bounded):** summarize supported dependencies and risks; unknown is valid.
5. **Human:** approve plan, access, recipients, dates and commitments.
6. **Code:** create tasks, collect evidence and send approved reminders.
7. **Human:** resolve exceptions and accept milestone evidence.
8. **Code:** assemble versioned steady-state packet.
9. **Human:** accept transfer and unresolved-item ownership.

## Idempotency, retry and rollback

- Keys: `handoff:{event_id}`, `case:{customer_id}:{agreement_id}`, `task:{case_id}:{milestone_version}:{task_key}`, `message:{case_id}:{template_version}:{recipient}:{purpose}`.
- Retry reads and internal writes with bounded backoff. Reconcile an external effect by its returned ID before retrying.
- Rollback cancels only unexecuted tasks/messages. Correct completed effects through compensating events; never delete history.

## Permissions and sensitive data

Use least-privilege service roles. Exclude undeclared sensitive fields from model context and test fixtures. Record purpose, allowed roles, retention event and disposal owner for every copied dataset.

## Exception routes

- Duplicate/conflicting identity -> identity owner.
- Missing scope/outcome -> commercial owner.
- Access/data-purpose issue -> privacy/security owner.
- Customer dependency expiry -> onboarding owner.
- Rejected evidence -> milestone owner.
- No exception owner -> safe stop.

## Acceptance tests

1. Duplicate trigger creates no duplicate case or task.
2. Missing outcome blocks communication and names its owner.
3. Conflicting scope blocks plan approval.
4. Model returns unknown when a dependency lacks evidence.
5. Expired approver cannot resume the workflow.
6. Rejected milestone preserves the prior evidence and decision.
7. Partial message failure retries only the missing effect.
8. Completion is impossible without receiving-owner acceptance.

## Audit record

Retain event/run IDs, definition and input versions, state transitions, source references, approvals/rejections, external effect IDs, exceptions, retries, corrections and final acceptance.