feat: implement onboarding journeys

docs/onboarding-journeys-and-welcome-protocols.md

@@ -0,0 +1,91 @@
+# 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 surfaces are left to USER-WP-0014.