feat: implement onboarding journeys

src/user_engine/ports.py

@@ -28,12 +28,14 @@ from user_engine.domain import (
     FamilyInvitation,
     IdentityFactor,
     Membership,
+    OnboardingJourney,
     OutboxEvent,
     PreparedAccount,
     ProfileValue,
     RegistrationSession,
     TenantAccount,
     User,
+    WelcomeProtocol,
 )
 
 
@@ -185,6 +187,33 @@ class UserEngineStore(Protocol):
     ) -> tuple[ActiveAccessContext, ...]:
         """Return active access contexts for a tenant."""
 
+    def save_welcome_protocol(self, protocol: WelcomeProtocol) -> None:
+        """Create or replace a welcome protocol template."""
+
+    def welcome_protocol(self, protocol_id: str) -> WelcomeProtocol | None:
+        """Return a welcome protocol template by id."""
+
+    def welcome_protocols_for_tenant(
+        self, tenant: str
+    ) -> tuple[WelcomeProtocol, ...]:
+        """Return welcome protocol templates for a tenant."""
+
+    def save_onboarding_journey(self, journey: OnboardingJourney) -> None:
+        """Create or replace an onboarding journey."""
+
+    def onboarding_journey(self, journey_id: str) -> OnboardingJourney | None:
+        """Return an onboarding journey by id."""
+
+    def onboarding_journeys_for_user(
+        self, user_id: str, *, tenant: str | None = None
+    ) -> tuple[OnboardingJourney, ...]:
+        """Return onboarding journeys for a user."""
+
+    def onboarding_journeys_for_tenant(
+        self, tenant: str
+    ) -> tuple[OnboardingJourney, ...]:
+        """Return onboarding journeys for a tenant."""
+
     def save_profile_value(self, value: ProfileValue) -> None:
         """Create or replace a profile value."""
 
@@ -260,6 +289,41 @@ class AccessControlFactExporter(Protocol):
         """Return an adapter-neutral access-control fact manifest."""
 
 
+class OnboardingNotificationPort(Protocol):
+    """Notify a delivery system about onboarding journey state."""
+
+    def notify(self, journey: OnboardingJourney) -> Mapping[str, Any]:
+        """Return adapter metadata for a notification request."""
+
+
+class OnboardingTaskPort(Protocol):
+    """Create or link external lifecycle tasks for onboarding steps."""
+
+    def link_task(self, journey: OnboardingJourney, step_key: str) -> Mapping[str, Any]:
+        """Return task-link metadata for one onboarding step."""
+
+
+class SupportContentPort(Protocol):
+    """Resolve support or help content references for onboarding."""
+
+    def content_ref(self, protocol: WelcomeProtocol, step_key: str) -> str | None:
+        """Return an adapter-owned content reference for a protocol step."""
+
+
+class SubsystemWelcomePort(Protocol):
+    """Call a protected subsystem welcome callback."""
+
+    def start(self, journey: OnboardingJourney, step_key: str) -> Mapping[str, Any]:
+        """Return callback metadata for a subsystem welcome step."""
+
+
+class LifecycleTaskLinkPort(Protocol):
+    """Link onboarding journeys to external lifecycle task systems."""
+
+    def link(self, journey: OnboardingJourney) -> Mapping[str, Any]:
+        """Return lifecycle task references for an onboarding journey."""
+
+
 class EventOutbox(Protocol):
     """Persist and publish durable domain events."""