# Onboarding Journeys And Welcome Protocols

Status: implemented headless slice
Date: 2026-06-15
Related workplan: USER-WP-0013

## Purpose

This slice adds resumable onboarding journeys for newly registered or newly
entitled users. Welcome protocols are templates that can be triggered by
registration completion, prepared-account claims, invitations, access-profile
events, or explicit manual starts.

user-engine owns journey state, audit/event correlation, lifecycle gaps, and
adapter references. Notification delivery, support content, protected service
tours, and external workflow/task systems remain outside the core domain.

## Domain Model

`WelcomeProtocol` is the tenant-scoped template. It stores trigger type,
optional matching keys such as prepared journey, application, realm, service,
role, hat, factor requirements, and ordered `WelcomeProtocolStep` definitions.

`WelcomeProtocolStep` names the subsystem, task kind, optional external task
reference, optional callback reference, support reference, and whether a
subsystem callback is required.

`OnboardingJourney` is the persisted user state. It records tenant, user,
protocol, trigger type, source id/event, journey key, status, active step,
correlation id, and timestamps.

`OnboardingStep` carries step status plus optional `OnboardingTask` and
`SubsystemHandoff` references. Missing required subsystem callbacks produce
explicit lifecycle gaps such as
`subsystem-callback-missing:<subsystem>:<step>`.

## Public Facade

`UserEngineService` exposes:

- `register_welcome_protocol(...)`
- `list_welcome_protocols(...)`
- `start_onboarding_journey(...)`
- `start_onboarding_for_registration(...)`
- `start_onboarding_for_prepared_account(...)`
- `progress_onboarding_step(...)`
- `complete_onboarding_step(...)`
- `skip_onboarding_step(...)`
- `fail_onboarding_step(...)`
- `resume_onboarding_journey(...)`
- `onboarding_diagnostics(...)`

Registration completion auto-starts matching registration protocols. Prepared
account claim auto-starts matching prepared-account protocols when the claimed
package includes a matching onboarding journey key.

## Lifecycle Rules

Journey status is derived from step state:

- a missing required callback starts the journey as `blocked`;
- an active non-blocked first step starts as `in_progress`;
- failed steps fail the journey;
- all completed/skipped steps complete the journey;
- all skipped steps skip the journey.

Resuming a pending, blocked, or failed journey can attach callback references
and returns blocked/failed steps to `in_progress`.

## Adapter Boundary

The service defines ports for notification delivery, task systems, support
content, subsystem welcome callbacks, and lifecycle task linking. The current
headless slice stores adapter references but does not call external systems.

## Identity Context And Diagnostics

`identity_context` includes onboarding journeys for the resolved user/tenant.
`onboarding_diagnostics` reports protocol count, journey count, status counts,
blocked step ids, and lifecycle gaps.

Diagnostics and outbox events avoid factor values and service content. Payloads
carry ids, statuses, trigger types, source ids, active step keys, and lifecycle
gap identifiers.

## Current Limits

- No notification platform or support-content renderer is implemented.
- No protected subsystem tour is hard-coded into user-engine.
- External task and callback execution is left to adapters.
- UI surface contracts are implemented by USER-WP-0014.