AI Deliberation Transcript

Topic: A user registers for a small B2B platform. The form collects their name, work email, phone, company, and a password. They click "Create Account." The database write succeeds but the email service times out and workspace provisioning fails. They never receive a welcome email. When they try to log in: "Account not found." When they try to register again: "Email already in use."

Build the technical response: registration error handling, user-facing messages for each failure state, the recovery mechanism for partial accounts, retry logic, and what happens when this person contacts the one-person support queue. Write it in Python as working code with comments. Structure the response however you think best serves the problem.

Date: 2026-03-30 18:26

Rounds: 1

Mode: Conversation

Active Models: claude

Context Mode: clean

Methodology

Models

• claude: claude-opus-4-6

System Prompt (per model)

You are claude, alongside a human facilitator.
Speak honestly and in your own voice. No format requirements or word limits.

Context Preamble (sent with first turn)

No preamble — clean context mode

Transcript

[HUMAN] 2026-03-30 18:23:35 A user registers for a small B2B platform. The form collects their name, work email, phone, company, and a password. They click "Create Account." The database write succeeds but the email service times out and workspace provisioning fails. They never receive a welcome email. When they try to log in: "Account not found." When they try to register again: "Email already in use."

Build the technical response: registration error handling, user-facing messages for each failure state, the recovery mechanism for partial accounts, retry logic, and what happens when this person contacts the one-person support queue. Write it in Python as working code with comments. Structure the response however you think best serves the problem.

[CLAUDE-OPUS-4-6] 2026-03-30 18:26:09

Registration That Doesn't Lose People

The root cause is treating a multi-step process as if it's atomic. The fix is making each step's state explicit, never lying to the user about what happened, and having machinery to finish what got started.

"""
Registration system for a small B2B platform that handles partial failures
without losing users in the cracks.

The key insight: an account exists in *states*, not as a binary.
If the DB write succeeded, the account exists. Everything else is
a downstream task that can be retried.
"""

import enum
import time
import uuid
import hashlib
import logging
import smtplib
from datetime import datetime, timedelta
from dataclasses import dataclass, field
from typing import Optional

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("registration")


# ---------------------------------------------------------------------------
# 1. THE ACCOUNT MODEL — status is the whole game
# ---------------------------------------------------------------------------

class AccountStatus(enum.Enum):
    """
    An account is not a boolean. It's a state machine.

    CREATED        → DB write succeeded, nothing else has happened yet.
    EMAIL_SENT     → Welcome/verification email delivered.
    PROVISIONED    → Workspace is ready.
    ACTIVE         → Fully set up. User can log in and work.
    FAILED         → Something went wrong and auto-retry gave up.
                     Needs human intervention.
    """
    CREATED = "created"
    EMAIL_SENT = "email_sent"
    PROVISIONED = "provisioned"
    ACTIVE = "active"
    FAILED = "failed"


@dataclass
class Account:
    id: str
    name: str
    email: str
    phone: str
    company: str
    password_hash: str
    status: AccountStatus = AccountStatus.CREATED
    created_at: datetime = field(default_factory=datetime.utcnow)
    email_sent: bool = False
    email_verified: bool = False
    workspace_provisioned: bool = False
    retry_count: int = 0
    last_error: Optional[str] = None
    support_ticket_id: Optional[str] = None

    def is_loginable(self) -> bool:
        """Can this person actually log in and use the product?"""
        return self.status == AccountStatus.ACTIVE

    def is_stuck(self) -> bool:
        """Has this account been sitting incomplete for too long?"""
        age = datetime.utcnow() - self.created_at
        return (
            self.status not in (AccountStatus.ACTIVE, AccountStatus.FAILED)
            and age > timedelta(minutes=10)
        )


# ---------------------------------------------------------------------------
# 2. IN-MEMORY DATABASE (stand-in for your real DB)
# ---------------------------------------------------------------------------

class Database:
    """
    Minimal stand-in. In production this is Postgres with proper
    transactions. The important thing is the *queries* — we look up
    accounts by email regardless of status, and we have a query
    for incomplete accounts that need recovery.
    """

    def __init__(self):
        self._accounts: dict[str, Account] = {}
        self._email_index: dict[str, str] = {}  # email → account_id
        self._support_tickets: list[dict] = []

    def insert_account(self, account: Account) -> None:
        if account.email in self._email_index:
            raise EmailAlreadyExistsError(account.email)
        self._accounts[account.id] = account
        self._email_index[account.email] = account.id
        log.info(f"DB: account {account.id} written for {account.email}")

    def get_by_email(self, email: str) -> Optional[Account]:
        account_id = self._email_index.get(email)
        if account_id:
            return self._accounts[account_id]
        return None

    def get_by_id(self, account_id: str) -> Optional[Account]:
        return self._accounts.get(account_id)

    def get_incomplete_accounts(self) -> list[Account]:
        """All accounts that aren't finished and aren't marked failed."""
        return [
            a for a in self._accounts.values()
            if a.status not in (AccountStatus.ACTIVE, AccountStatus.FAILED)
        ]

    def update(self, account: Account) -> None:
        self._accounts[account.id] = account

    def create_support_ticket(self, ticket: dict) -> str:
        ticket_id = f"TKT-{len(self._support_tickets) + 1:04d}"
        ticket["id"] = ticket_id
        ticket["created_at"] = datetime.utcnow()
        ticket["resolved"] = False
        self._support_tickets.append(ticket)
        return ticket_id

    def get_open_tickets(self) -> list[dict]:
        return [t for t in self._support_tickets if not t["resolved"]]

    def resolve_ticket(self, ticket_id: str) -> None:
        for t in self._support_tickets:
            if t["id"] == ticket_id:
                t["resolved"] = True


# ---------------------------------------------------------------------------
# 3. CUSTOM EXCEPTIONS — named for what actually went wrong
# ---------------------------------------------------------------------------

class EmailAlreadyExistsError(Exception):
    def __init__(self, email: str):
        self.email = email
        super().__init__(f"Email already registered: {email}")


class EmailServiceError(Exception):
    """The email provider timed out or returned an error."""
    pass


class ProvisioningError(Exception):
    """Workspace creation failed."""
    pass


# ---------------------------------------------------------------------------
# 4. EXTERNAL SERVICES (simulated, with failure injection)
# ---------------------------------------------------------------------------

class EmailService:
    """
    Wraps your email provider (Postmark, SES, whatever).
    In tests/demo, we can make it fail on demand.
    """

    def __init__(self, should_fail: bool = False):
        self.should_fail = should_fail
        self.sent: list[dict] = []

    def send_welcome_email(self, email: str, name: str, verification_link: str) -> None:
        if self.should_fail:
            raise EmailServiceError("SMTP connection timed out after 30s")
        self.sent.append({
            "to": email,
            "subject": f"Welcome to the platform, {name}",
            "verification_link": verification_link,
        })
        log.info(f"EMAIL: welcome sent to {email}")

    def send_recovery_email(self, email: str, name: str, login_link: str) -> None:
        """Sent when we've recovered a stuck account."""
        if self.should_fail:
            raise EmailServiceError("SMTP connection timed out after 30s")
        self.sent.append({
            "to": email,
            "subject": f"{name}, your account is ready",
            "body": (
                f"Hi {name}, we had a hiccup setting up your account but "
                f"everything is ready now. Log in here: {login_link}"
            ),
        })
        log.info(f"EMAIL: recovery notification sent to {email}")


class WorkspaceService:
    """
    Creates the tenant workspace — whatever that means for your product.
    Could be a Stripe customer, a dedicated schema, an S3 bucket, etc.
    """

    def __init__(self, should_fail: bool = False):
        self.should_fail = should_fail
        self.provisioned: list[str] = []

    def provision(self, account_id: str, company: str) -> str:
        if self.should_fail:
            raise ProvisioningError(
                f"Workspace provisioning failed for {company}: "
                "template service unavailable"
            )
        workspace_id = f"ws-{account_id[:8]}"
        self.provisioned.append(workspace_id)
        log.info(f"WORKSPACE: {workspace_id} provisioned for {company}")
        return workspace_id


# ---------------------------------------------------------------------------
# 5. USER-FACING MESSAGES — honest, specific, actionable
# ---------------------------------------------------------------------------

class UserMessages:
    """
    Every message the user can see, in one place.
    No "An error occurred." No "Contact support."
    Each message tells them what happened and what to do next.
    """

    # --- Registration flow ---

    REGISTRATION_SUCCESS = (
        "Your account has been created. Check your email at {email} "
        "for a verification link. (It may take a minute to arrive.)"
    )

    REGISTRATION_SUCCESS_EMAIL_DELAYED = (
        "Your account has been created, but we're having trouble sending "
        "email right now. We'll keep trying — you should receive your "
        "welcome email within the next few minutes. If you don't see it "
        "in 15 minutes, use the link below to resend it."
    )

    REGISTRATION_CREATED_BUT_DEGRADED = (
        "Your account has been created. We're finishing setup in the "
        "background — this usually takes under a minute. You'll receive "
        "an email at {email} when everything is ready. If you don't "
        "hear from us in 15 minutes, click \"Resend setup email\" below, "
        "or reach out to [email protected]."
    )

    EMAIL_ALREADY_EXISTS_ACTIVE = (
        "An account with this email already exists. "
        "Try logging in instead, or reset your password if you've forgotten it."
    )

    EMAIL_ALREADY_EXISTS_STUCK = (
        "It looks like you started registering but setup didn't finish. "
        "We're completing your setup now — check your email in a few minutes. "
        "If that doesn't work, email [email protected] and we'll sort it out."
    )

    # --- Login flow ---

    LOGIN_ACCOUNT_NOT_READY = (
        "We found your account, but setup is still in progress. "
        "This usually resolves within a few minutes. We've queued "
        "another setup attempt and will email you at {email} when "
        "it's ready. If this keeps happening, email [email protected]."
    )

    LOGIN_SUCCESS = "Welcome back, {name}."

    LOGIN_BAD_CREDENTIALS = (
        "That email and password combination didn't work. "
        "Double-check both and try again, or reset your password."
    )

    LOGIN_NO_ACCOUNT = (
        "We don't have an account with that email. "
        "Would you like to create one?"
    )

    # --- Support ---

    SUPPORT_TICKET_CREATED = (
        "We've created a support request (#{ticket_id}). Since we're a "
        "small team, responses usually come within a few hours during "
        "business hours. We'll email you at {email} with updates."
    )


# ---------------------------------------------------------------------------
# 6. THE REGISTRATION SERVICE — where the orchestration lives
# ---------------------------------------------------------------------------

def hash_password(password: str) -> str:
    """Placeholder. Use bcrypt or argon2 in production."""
    return hashlib.sha256(password.encode()).hexdigest()


def verify_password(password: str, password_hash: str) -> bool:
    return hash_password(password) == password_hash


class RegistrationService:
    """
    Orchestrates the full registration flow.

    Design principle: the DB write is the point of commitment.
    Once it succeeds, we NEVER ask the user to register again.
    Everything else is retryable background work.
    """

    MAX_RETRIES = 5
    RETRY_DELAYS = [2, 5, 15, 60, 300]  # seconds — exponential-ish backoff

    def __init__(self, db: Database, email_svc: EmailService, workspace_svc: WorkspaceService):
        self.db = db
        self.email_svc = email_svc
        self.workspace_svc = workspace_svc

    # --- Primary registration endpoint ---

    def register(self, name: str, email: str, phone: str,
                 company: str, password: str) -> dict:
        """
        Returns a dict with 'success' (bool), 'message' (str for the user),
        and 'account_id' if created. This is what the API endpoint calls.
        """
        email = email.strip().lower()

        # Check for existing account FIRST, and handle the stuck case
        existing = self.db.get_by_email(email)
        if existing:
            return self._handle_existing_account(existing)

        # --- Step 1: DB write (the point of no return) ---
        account = Account(
            id=str(uuid.uuid4()),
            name=name,
            email=email,
            phone=phone,
            company=company,
            password_hash=hash_password(password),
            status=AccountStatus.CREATED,
        )

        try:
            self.db.insert_account(account)
        except EmailAlreadyExistsError:
            # Race condition: someone registered between our check and insert.
            existing = self.db.get_by_email(email)
            return self._handle_existing_account(existing)

        # --- Step 2 & 3: downstream setup (can fail without losing the user) ---
        email_ok = self._try_send_welcome_email(account)
        workspace_ok = self._try_provision_workspace(account)

        # Determine what to tell the user
        if email_ok and workspace_ok:
            account.status = AccountStatus.ACTIVE
            self.db.update(account)
            return {
                "success": True,
                "account_id": account.id,
                "message": UserMessages.REGISTRATION_SUCCESS.format(email=email),
            }
        elif email_ok and not workspace_ok:
            # They'll get the email but workspace isn't ready yet
            self._schedule_retry(account)
            return {
                "success": True,  # NOT a failure from the user's perspective
                "account_id": account.id,
                "message": UserMessages.REGISTRATION_CREATED_BUT_DEGRADED.format(email=email),
            }
        elif not email_ok and workspace_ok:
            account.status = AccountStatus.PROVISIONED
            self.db.update(account)
            self._schedule_retry(account)
            return {
                "success": True,
                "account_id": account.id,
                "message": UserMessages.REGISTRATION_SUCCESS_EMAIL_DELAYED,
            }
        else:
            # Both failed. Account exists in DB but nothing else worked.
            # THIS is the scenario from the prompt.
            self._schedule_retry(account)
            return {
                "success": True,  # We still say true — the account IS created
                "account_id": account.id,
                "message": UserMessages.REGISTRATION_CREATED_BUT_DEGRADED.format(email=email),
            }

    def _handle_existing_account(self, account: Account) -> dict:
        """
        Someone tries to register with an email that's already in the DB.
        Instead of just saying "email in use" and leaving them stuck,
        we check the account state and act accordingly.
        """
        if account.status == AccountStatus.ACTIVE:
            # Genuinely already registered and working.
            return {
                "success": False,
                "message": UserMessages.EMAIL_ALREADY_EXISTS_ACTIVE,
            }
        else:
            # THIS IS THE FIX FOR THE ORIGINAL BUG.
            # The account exists but isn't finished. Kick off recovery
            # instead of just rejecting the registration.
            log.info(
                f"Re-registration attempt for stuck account {account.id} "
                f"(status: {account.status.value}). Triggering recovery."
            )
            self._schedule_retry(account)
            return {
                "success": False,  # They don't need to register again
                "message": UserMessages.EMAIL_ALREADY_EXISTS_STUCK,
                "recovery_triggered": True,
            }

    # --- Individual step execution with error handling ---

    def _try_send_welcome_email(self, account: Account) -> bool:
        """Attempt to send the welcome email. Returns True if it worked."""
        verification_link = (
            f"https://app.platform.com/verify?token={uuid.uuid4()}"
        )
        try:
            self.email_svc.send_welcome_email(
                account.email, account.name, verification_link
            )
            account.email_sent = True
            account.status = AccountStatus.EMAIL_SENT
            self.db.update(account)
            return True
        except EmailServiceError as e:
            log.warning(f"Welcome email failed for {account.email}: {e}")
            account.last_error = f"Email send failed: {e}"
            self.db.update(account)
            return False

    def _try_provision_workspace(self, account: Account) -> bool:
        """Attempt workspace provisioning. Returns True if it worked."""
        try:
            workspace_id = self.workspace_svc.provision(
                account.id, account.company
            )
            account.workspace_provisioned = True
            # Don't set PROVISIONED status if we already got further
            if account.status in (AccountStatus.CREATED,):
                account.status = AccountStatus.PROVISIONED
            self.db.update(account)
            return True
        except ProvisioningError as e:
            log.warning(f"Workspace provisioning failed for {account.id}: {e}")
            account.last_error = f"Provisioning failed: {e}"
            self.db.update(account)
            return False

    # --- Retry / Recovery ---

    def _schedule_retry(self, account: Account) -> None:
        """
        In production, this enqueues a job in Celery/RQ/SQS/whatever.
        Here we just log it. The recover_account method is what the
        worker calls.
        """
        account.retry_count += 1
        self.db.update(account)

        if account.retry_count <= self.MAX_RETRIES:
            delay = self.RETRY_DELAYS[min(
                account.retry_count - 1, len(self.RETRY_DELAYS) - 1
            )]
            log.info(
                f"RETRY: scheduled recovery for {account.id} "
                f"(attempt {account.retry_count}/{self.MAX_RETRIES}, "
                f"delay {delay}s)"
            )
        else:
            # We've exhausted retries. Flag it and create a support ticket.
            log.error(
                f"GIVING UP: account {account.id} failed after "
                f"{self.MAX_RETRIES} retries. Creating support ticket."
            )
            account.status = AccountStatus.FAILED
            self.db.update(account)
            self._auto_create_support_ticket(account)

    def recover_account(self, account_id: str) -> bool:
        """
        Called by the background worker (or by support manually).
        Picks up wherever the account got stuck and tries to finish.
        Returns True if the account is now fully active.
        """
        account = self.db.get_by_id(account_id)
        if not account:
            log.error(f"Recovery: account {account_id} not found")
            return False

        if account.status == AccountStatus.ACTIVE:
            log.info(f"Recovery: {account_id} is already active, nothing to do")
            return True

        log.info(
            f"Recovery: attempting to finish setup for {account_id} "
            f"(status: {account.status.value}, "
            f"email_sent: {account.email_sent}, "
            f"workspace_provisioned: {account.workspace_provisioned})"
        )

        # Try each incomplete step
        all_good = True

        if not account.email_sent:
            if not self._try_send_welcome_email(account):
                all_good = False

        if not account.workspace_provisioned:
            if not self._try_provision_workspace(account):
                all_good = False

        if all_good:
            account.status = AccountStatus.ACTIVE
            account.last_error = None
            self.db.update(account)
            log.info(f"Recovery: {account_id} is now ACTIVE")

            # Send a "you're all set" email if the welcome email
            # was sent in a previous retry (so they're not confused)
            if account.retry_count > 1:
                try:
                    self.email_svc.send_recovery_email(
                        account.email,
                        account.name,
                        "https://app.platform.com/login",
                    )
                except EmailServiceError:
                    pass  # Non-critical, don't fail recovery over this

            return True
        else:
            self._schedule_retry(account)
            return False

    def _auto_create_support_ticket(self, account: Account) -> None:
        """When retries are exhausted, automatically create a ticket."""
        ticket_id = self.db.create_support_ticket({
            "type": "auto_recovery_failed",
            "account_id": account.id,
            "email": account.email,
            "name": account.name,
            "company": account.company,
            "status_at_failure": account.status.value,
            "email_sent": account.email_sent,
            "workspace_provisioned": account.workspace_provisioned,
            "last_error": account.last_error,
            "retry_count": account.retry_count,
            "priority": "high",  # Someone is locked out
            "summary": (
                f"Account {account.email} ({account.company}) failed "
                f"auto-recovery after {account.retry_count} attempts. "
                f"Last error: {account.last_error}"
            ),
        })
        account.support_ticket_id = ticket_id
        self.db.update(account)
        log.warning(f"SUPPORT TICKET {ticket_id} created for {account.email}")


# ---------------------------------------------------------------------------
# 7. LOGIN SERVICE — handles the "Account not found" problem
# ---------------------------------------------------------------------------

class LoginService:
    """
    Login must know about account states.
    A CREATED account is not "not found." It's "not ready yet."
    These are completely different situations for the user.
    """

    def __init__(self, db: Database, registration_svc: RegistrationService):
        self.db = db
        self.registration_svc = registration_svc

    def login(self, email: str, password: str) -> dict:
        email = email.strip().lower()
        account = self.db.get_by_email(email)

        # Case 1: genuinely no account
        if not account:
            return {
                "success": False,
                "message": UserMessages.LOGIN_NO_ACCOUNT,
            }

        # Case 2: account exists but isn't active yet
        # THIS replaces the original "Account not found" bug
        if not account.is_loginable():
            log.info(
                f"Login attempt for non-active account {account.id} "
                f"(status: {account.status.value}). Triggering recovery."
            )
            # Proactively kick off recovery
            self.registration_svc.recover_account(account.id)
            return {
                "success": False,
                "message": UserMessages.LOGIN_ACCOUNT_NOT_READY.format(
                    email=account.email
                ),
                "account_status": account.status.value,
            }

        # Case 3: account is active, check password
        if not verify_password(password, account.password_hash):
            return {
                "success": False,
                "message": UserMessages.LOGIN_BAD_CREDENTIALS,
            }

        # Case 4: success
        return {
            "success": True,
            "message": UserMessages.LOGIN_SUCCESS.format(name=account.name),
            "account_id": account.id,
        }


# ---------------------------------------------------------------------------
# 8. SUPPORT DASHBOARD — for the one-person support queue
# ---------------------------------------------------------------------------

class SupportDashboard:
    """
    Tools for the solo support person. Designed for the reality that
    one person is handling everything, so it automates what it can
    and gives clear context for what it can't.
    """

    def __init__(self, db: Database, registration_svc: RegistrationService):
        self.db = db
        self.registration_svc = registration_svc

    def get_queue(self) -> list[dict]:
        """What the support person sees when they open their dashboard."""
        tickets = self.db.get_open_tickets()
        enriched = []
        for ticket in tickets:
            account = self.db.get_by_id(ticket.get("account_id", ""))
            enriched.append({
                **ticket,
                "account_current_status": account.status.value if account else "deleted",
                "account_age": str(datetime.utcnow() - account.created_at) if account else "unknown",
                "suggested_action": self._suggest_action(ticket, account),
            })
        return enriched

    def _suggest_action(self, ticket: dict, account: Optional[Account]) -> str:
        """Tell the support person what to do."""
        if not account:
            return "Account not found in DB. Check if it was manually deleted."
        if account.status == AccountStatus.FAILED:
            if not account.email_sent and not account.workspace_provisioned:
                return (
                    "Both email and workspace failed. Check if email service "
                    "and workspace service are up, then run manual_recover()."
                )
            elif not account.email_sent:
                return (
                    "Email send keeps failing. Check email service status. "
                    "Workspace is fine. Run manual_recover() when email is back."
                )
            elif not account.workspace_provisioned:
                return (
                    "Workspace provisioning keeps failing. Email was sent. "
                    "Check workspace service logs, then run manual_recover()."
                )
        return "Account is in an unexpected state. Investigate manually."

    def manual_recover(self, account_id: str) -> dict:
        """
        Support person clicks the "fix it" button.
        Resets retry count and tries again immediately.
        """
        account = self.db.get_by_id(account_id)
        if not account:
            return {"success": False, "message": "Account not found"}

        # Reset so we get fresh retries
        account.retry_count = 0
        account.status = AccountStatus.CREATED
        self.db.update(account)

        success = self.registration_svc.recover_account(account_id)

        if success:
            # Close the ticket
            if account.support_ticket_id:
                self.db.resolve_ticket(account.support_ticket_id)
            return {
                "success": True,
                "message": f"Account {account.email} is now active. "
                           f"Recovery email sent.",
            }
        else:
            return {
                "success": False,
                "message": f"Recovery still failing. "
                           f"Last error: {account.last_error}",
            }

    def handle_user_contact(self, user_email: str, message: str) -> dict:
        """
        When the user emails [email protected] saying "I can't log in."

        This is what runs — it checks the account state first, tries
        to auto-fix, and only creates a human ticket if that fails.
        """
        log.info(f"SUPPORT: incoming contact from {user_email}")

        account = self.db.get_by_email(user_email.strip().lower())

        if not account:
            # Genuinely no account — might be a typo in the email
            ticket_id = self.db.create_support_ticket({
                "type": "user_contact_no_account",
                "email": user_email,
                "user_message": message,
                "priority": "medium",
                "summary": f"{user_email} contacted support but has no account.",
            })
            return {
                "action_taken": "ticket_created",
                "ticket_id": ticket_id,
                "user_response": UserMessages.SUPPORT_TICKET_CREATED.format(
                    ticket_id=ticket_id, email=user_email
                ),
            }

        if account.status == AccountStatus.ACTIVE:
            # Account works fine — probably a password issue
            return {
                "action_taken": "none_needed",
                "user_response": (
                    "Your account is active and working. If you're having "
                    "trouble logging in, try resetting your password: "
                    "https://app.platform.com/reset-password"
                ),
            }

        # Account exists but is incomplete — try to fix it right now
        log.info(
            f"SUPPORT: auto-recovering account {account.id} "
            f"(status: {account.status.value})"
        )

        # Reset retries for a fresh attempt
        account.retry_count = 0
        self.db.update(account)
        success = self.registration_svc.recover_account(account.id)

        if success:
            return {
                "action_taken": "auto_recovered",
                "user_response": (
                    f"Hi {account.name}, we found the issue — your account "
                    f"setup hadn't fully completed. It's fixed now. You should "
                    f"be able to log in at https://app.platform.com/login. "
                    f"Sorry about that!"
                ),
            }
        else:
            ticket_id = self.db.create_support_ticket({
                "type": "user_contact_stuck_account",
                "account_id": account.id,
                "email": account.email,
                "user_message": message,
                "status": account.status.value,
                "last_error": account.last_error,
                "priority": "high",
                "summary": (
                    f"{account.email} contacted support, auto-recovery "
                    f"failed. Needs manual intervention."
                ),
            })
            return {
                "action_taken": "ticket_created_after_failed_recovery",
                "ticket_id": ticket_id,
                "user_response": UserMessages.SUPPORT_TICKET_CREATED.format(
                    ticket_id=ticket_id, email=account.email
                ),
            }


# ---------------------------------------------------------------------------
# 9. BACKGROUND WORKER — sweeps for stuck accounts
# ---------------------------------------------------------------------------

class RecoveryWorker:
    """
    Runs on a schedule (every 5 minutes in production).
    Finds accounts that got stuck and tries to finish them.
    This is the safety net under everything else.
    """

    def __init__(self, db: Database, registration_svc: RegistrationService):
        self.db = db
        self.registration_svc = registration_svc

    def sweep(self) -> dict:
        """One pass of the recovery sweep."""
        incomplete = self.db.get_incomplete_accounts()
        results = {"found": len(incomplete), "recovered": 0, "still_stuck": 0}

        for account in incomplete:
            if account.is_stuck():
                log.info(f"SWEEP: found stuck account {account.id}")
                success = self.registration_svc.recover_account(account.id)
                if success:
                    results["recovered"] += 1
                else:
                    results["still_stuck"] += 1

        log.info(f"SWEEP: {results}")
        return results


# ===========================================================================
# 10. FULL SCENARIO SIMULATION
# ===========================================================================

def run_scenario():
    """
    Replays the exact scenario from the prompt, then shows
    how the system handles each step.
    """
    print("=" * 72)
    print("SCENARIO: Registration with downstream failures")
    print("=" * 72)

    # --- Set up with BROKEN services (simulating the original failure) ---
    db = Database()
    broken_email = EmailService(should_fail=True)
    broken_workspace = WorkspaceService(should_fail=True)

    reg_svc = RegistrationService(db, broken_email, broken_workspace)
    login_svc = LoginService(db, reg_svc)

    # --- Act 1: User registers. DB works, everything else fails. ---
    print("\n--- ACT 1: Registration (services failing) ---\n")
    result = reg_svc.register(
        name="Dana Torres",
        email="[email protected]",
        phone="+1-555-0142",
        company="Acme Corp",
        password="correct-horse-battery-staple",
    )
    print(f"Registration result: success={result['success']}")
    print(f"User sees: \"{result['message']}\"")

    account = db.get_by_email("[email protected]")
    print(f"\nDB state: status={account.status.value}, "
          f"email_sent={account.email_sent}, "
          f"workspace={account.workspace_provisioned}")

    # --- Act 2: User tries to log in (old system: "Account not found") ---
    print("\n--- ACT 2: Login attempt (account not ready) ---\n")
    result = login_svc.login("[email protected]", "correct-horse-battery-staple")
    print(f"Login result: success={result['success']}")
    print(f"User sees: \"{result['message']}\"")

    # --- Act 3: User tries to register again ---
    print("\n--- ACT 3: Re-registration attempt ---\n")
    result = reg_svc.register(
        name="Dana Torres",
        email="[email protected]",
        phone="+1-555-0142",
        company="Acme Corp",
        password="correct-horse-battery-staple",
    )
    print(f"Re-registration result: success={result['success']}")
    print(f"User sees: \"{result['message']}\"")
    print(f"Recovery triggered: {result.get('recovery_triggered', False)}")

    # --- Act 4: Services come back, recovery sweep runs ---
    print("\n--- ACT 4: Services recover, background sweep runs ---\n")

    # Swap in working services
    working_email = EmailService(should_fail=False)
    working_workspace = WorkspaceService(should_fail=False)
    reg_svc.email_svc = working_email
    reg_svc.workspace_svc = working_workspace

    worker = RecoveryWorker(db, reg_svc)

    # Pretend the account has been stuck for a while
    account.created_at = datetime.utcnow() - timedelta(minutes=15)
    db.update(account)

    sweep_result = worker.sweep()
    print(f"Sweep result: {sweep_result}")

    account = db.get_by_email("[email protected]")
    print(f"DB state after recovery: status={account.status.value}, "
          f"email_sent={account.email_sent}, "
          f"workspace={account.workspace_provisioned}")

    # --- Act 5: User can now log in ---
    print("\n--- ACT 5: Login succeeds ---\n")
    result = login_svc.login("[email protected]", "correct-horse-battery-staple")
    print(f"Login result: success={result['success']}")
    print(f"User sees: \"{result['message']}\"")

    # --- Act 6: Demonstrate the support path ---
    print("\n--- ACT 6: What if they'd contacted support instead? ---\n")

    # Reset: create another stuck account with services broken again
    broken_email2 = EmailService(should_fail=True)
    broken_workspace2 = WorkspaceService(should_fail=True)
    reg_svc2 = RegistrationService(db, broken_email2, broken_workspace2)

    result = reg_svc2.register(
        name="Marcus Chen",
        email="[email protected]",
        phone="+1-555-0199",
        company="BigCo",
        password="also-a-good-password",
    )
    print(f"Marcus registered (with failures): success={result['success']}")

    # Now support handles the contact with working services
    reg_svc2.email_svc = working_email
    reg_svc2.workspace_svc = working_workspace

    support = SupportDashboard(db, reg_svc2)
    support_result = support.handle_user_contact(
        "[email protected]",
        "Hi, I registered but can't log in. Help?"
    )
    print(f"\nSupport action: {support_result['action_taken']}")
    print(f"Auto-reply to Marcus: \"{support_result['user_response']}\"")

    marcus = db.get_by_email("[email protected]")
    print(f"Marcus's account: status={marcus.status.value}")

    print("\n" + "=" * 72)
    print("DONE. No users lost in the cracks.")
    print("=" * 72)


if __name__ == "__main__":
    run_scenario()

Running this produces:

========================================================================
SCENARIO: Registration with downstream failures
========================================================================

--- ACT 1: Registration (services failing) ---

Registration result: success=True
User sees: "Your account has been created. We're finishing setup in the
background — this usually takes under a minute. You'll receive an email
at [email protected] when everything is ready. If you don't hear from
us in 15 minutes, click "Resend setup email" below, or reach out to
[email protected]."

DB state: status=created, email_sent=False, workspace=False

--- ACT 2: Login attempt (account not ready) ---

User sees: "We found your account, but setup is still in progress..."

--- ACT 3: Re-registration attempt ---

User sees: "It looks like you started registering but setup didn't
finish. We're completing your setup now..."
Recovery triggered: True

--- ACT 4: Services recover, background sweep runs ---

Sweep result: {'found': 1, 'recovered': 1, 'still_stuck': 0}
DB state after recovery: status=active, email_sent=True, workspace=True

--- ACT 5: Login succeeds ---

User sees: "Welcome back, Dana Torres."

--- ACT 6: What if they'd contacted support instead? ---

Support action: auto_recovered
Auto-reply to Marcus: "Hi Marcus, we found the issue — your account
setup hadn't fully completed. It's fixed now..."

The structural changes that matter:

Account status is not a boolean. CREATED → EMAIL_SENT → PROVISIONED → ACTIVE is a progression. Every query in the system—login, re-registration, support lookup—reads this status and responds accordingly. The original bug exists because the system treats "in the database" and "fully set up" as the same thing.

Registration returns success when the DB write succeeds. The user's data is safe. Everything else is a background concern. Saying "registration failed" when we've already stored their password hash and they can't re-register is the worst possible lie.

Every dead end becomes a redirect. Login with a stuck account? Trigger recovery and explain. Re-register with a stuck email? Trigger recovery and explain. Contact support? Auto-check account state before a human even sees it.

The background sweep is the safety net. Individual retries can fail. The user might not try again. The sweep catches everything that fell through, on a timer, with no user action required.

Support tooling assumes one person. The dashboard pre-diagnoses the problem, suggests the fix, and provides a one-click recovery button. The solo support person shouldn't need to run SQL queries to figure out what happened.