---
kind: task
slug: account-merge
title: Merge two existing user accounts that turn out to share an email
plan_slug: multitenant-saas-hardening
epic_slug: tenant-lifecycle
status: draft
priority: P2
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-06-02"
---

# Task summary

Handle the case where a user has, historically, created two separate `users` rows (one via GitHub OAuth, one via Credentials, etc.) and now wants them merged into a single identity. The current behavior in `Task-multi-email-identity` is to *reject* the OAuth sign-in when the email collides with another user — this task is the operator-facing fix.

## Why deferred from the invites convoy

Account merge is security-sensitive and has cascading data implications:

- Both users may have authored `objects`, posted comments, owned workspaces, accepted invites.
- After merge, all FKs on the losing user's id need to point to the winning user's id, in one transaction.
- Some FKs have unique constraints (e.g., `workspace_members(workspace_id, user_id)`) — merging two users who are both in the same workspace creates a conflict that has to be resolved by keeping the higher-role row.
- Requires both accounts to prove ownership (re-sign-in to the losing account, then OAuth-verify the winning account's email).

This is its own multi-day effort. Out of scope for the invites convoy.

## Scope (sketch — refine when scheduled)

- Detection: when `ensureUserIdByVerifiedEmail` would reject an OAuth sign-in because the email is verified on another user, instead surface a "we found another account with this email — merge?" affordance.
- Merge procedure: a transactional operator that rewires FKs from the losing user to the winning user, handles unique-constraint collisions per table, and writes a comprehensive audit-log entry.
- UI: profile-side "Merge another account into this one" flow that requires authenticating to both.

## Acceptance criteria (draft)

- [ ] All FKs that referenced the losing user now reference the winning user; no orphans.
- [ ] Workspace-membership conflicts resolved with the higher-role row kept.
- [ ] Audit-log entry includes a snapshot of every rewired FK count.
- [ ] Losing user row is hard-deleted only after a 30-day window during which the merge can be reverted (soft-delete first; reuses `Task-workspace-soft-delete-and-audit` semantics).

## Links

- Epic: `./Epic-tenant-lifecycle.md`
- Depends on: `./Task-multi-email-identity.md`, `./Task-workspace-soft-delete-and-audit.md`.