PSA/ee/docs/plans/2026-06-01-tenant-reactivation-winback/SCRATCHPAD.md

# SCRATCHPAD — Tenant Reactivation / Win-Back

Working memory for the effort. Spans two repos: `alga-psa` (app/auth/billing/temporal)
and `nm-store` (marketing + order/checkout site).

## Core insight (why this is feasible)

Tenant deletion is **not destructive up front**. `customer.subscription.deleted`
→ `tenantDeletionWorkflow` runs a *staged, reversible* process: export data → deactivate
users (`is_inactive=true`) → tag client "Canceled" → write `pending_tenant_deletions`
row (`scheduled_deletion_date = now + 90d`) → **`await condition(…, 90 days)`**. Data
stays intact and the workflow stays alive/listening for up to 90 days. There is already a
`rollbackDeletion` signal that un-does it (reactivate users, remove tag, reactivate master
client). That 90-day window IS the reactivation window.

**Point of no return:** when the pending-deletion `status` flips to `deleting`/`deleted`.
Before that → reactivatable. After that → data gone (only S3 export remains; out of scope).

## Product decisions (user-confirmed 2026-06-01)

- **Payment policy:** reactivation requires a **new paid subscription at full price —
  NO first-month/intro discount and no trial.** (Mechanism: omit `introCouponId` and any
  `trial_period_days` when building the reactivation checkout.)
- **Login UX:** **email-only.** Keep the generic "invalid credentials" response; do NOT
  add a distinguishable pending-deletion login screen. Silently fire a (throttled) win-back
  email on a login *attempt* to an inactive + mid-deletion account — password is NOT verified
  (the gate short-circuits before verifyPassword); intent is confirmed downstream by payment.
  (Superseded the earlier "correct-password" framing — see §8 / Review-1 correction.)
- **Both entry points funnel into one reactivation funnel:** paid re-subscribe (no discount)
  → rollback signal (reactivate, data preserved) → link new subscription to the EXISTING
  tenant → password reset.

## File map (verified)

### Deletion lifecycle (alga / ee)
- Workflow: `ee/temporal-workflows/src/workflows/tenant-deletion-workflow.ts`
  - rollback handler ~`:432-476` (reactivate users, remove Canceled tag, reactivate master
    client, status `rolled_back`); grace wait `await condition(…, DAYS_90_MS)`.
- Activity `recordPendingDeletion`: `ee/temporal-workflows/src/activities/tenant-deletion-activities.ts:1032-1086`
  → table **`pending_tenant_deletions`** (col `tenant` uuid, `status`, `workflow_id`,
  `workflow_run_id`, `subscription_external_id`, `canceled_at`, `scheduled_deletion_date`,
  `stats_snapshot`). Migration: `ee/server/migrations/20260113120000_create_pending_tenant_deletions.cjs`
  (`table.unique(['tenant'])` → one active deletion per tenant; status lifecycle
  `pending|awaiting_confirmation|confirmed|deleting|deleted|rolled_back|failed`).
- Status query pattern (active row): `whereNotIn('status', ['deleted','rolled_back','failed'])`
  — already used in `start-deletion/route.ts:110-113`.

### Cancellation → deletion triggers
- Stripe: `ee/server/src/lib/stripe/StripeService.ts` — dispatch `case 'customer.subscription.deleted'`
  `:1106-1107`; `handleSubscriptionDeleted` `:1514-1585` → `startTenantDeletionWorkflow({…
  triggerSource:'stripe_webhook'…})` `:1560-1565` (failures swallowed).
- Apple IAP: `server/src/app/api/v1/mobile/iap/notifications/route.ts:228-233`.
- Manual/extension: `ee/server/src/app/api/v1/tenant-management/start-deletion/route.ts:150-155`.

### Signaling a live deletion workflow (reactivation mechanism)
- `ee/server/src/lib/tenant-management/workflowClient.ts`
  - `startTenantDeletionWorkflow` `:169-212` (workflowId = `tenant-deletion-${tenantId}-${Date.now()}`)
  - `rollbackTenantDeletion(workflowId, reason, rolledBackBy)` `:301-339` → `handle.signal('rollbackDeletion', …)`
  - `getTenantDeletionState(workflowId)` `:217-253` (query 'getState')
  - **DUP COPY** at `packages/ee/src/lib/tenant-management/workflowClient.ts` — keep in sync.
- HTTP (master-tenant auth only): `ee/server/src/app/api/v1/tenant-management/rollback-deletion/route.ts`
  (rejects if status already `deleted`/`rolled_back`/`deleting`).
  - nm-store can't use master-tenant auth → need a new **HMAC service-to-service** entry.

### Login / auth
- NextAuth: `packages/auth/src/lib/nextAuthOptions.ts` `authorize` `:1183-1408` → `authenticateUser(…)`.
- `authenticateUser`: `packages/auth/src/actions/auth.tsx:16-104`.
  - **CORRECTED (was wrong earlier):** the order is `:87 if (user.is_inactive) return null;` THEN
    `:97 verifyPassword(...)`. So the `is_inactive` gate short-circuits **before** the password is
    ever checked. The password is NOT verified for inactive users → at the hook point we CANNOT
    confirm identity. (My prior note claiming "password verified before the gate" was false.)
  - Implication: login win-back does NOT verify the password. At the `:87` gate, if an active
    pending deletion exists for `user.tenant`, fire the throttled reactivate-invite email
    (fire-and-forget), then return null as today. No reorder, no verifyPassword call. Intent is
    confirmed downstream by PAYMENT, not the login attempt. 14-day throttle = anti-spam (not intent).
  - Deactivation (`deactivateAllTenantUsers`) only sets `is_inactive=true` — `hashed_password` is
    preserved → keep-old-password would work, but we default to FORCE password-reset on reactivation
    (email-ownership check after payment).

### nm-store order/checkout + existing-tenant check
- alga endpoint: `server/src/app/api/billing/check-tenant/route.ts` (`GET …?email=`, HMAC
  `x-webhook-signature = HMAC-SHA256("email:timestamp", ALGA_WEBHOOK_SECRET)`). Returns
  `{exists, tenantId, tenantName}` / 404 `{exists:false}`. Does NOT currently consider
  `pending_tenant_deletions` or `is_inactive`.
- nm-store: `utils/alga-api.ts:119-178` `checkTenantExists`; `actions/email-validation.ts:11-26`
  `checkExistingTenant`; `components/OrderForm.tsx:755` `validateEmailAvailability` `:741-784`,
  hard block `:786-827` ("A tenant already exists for this email.").

### Password reset
- `packages/auth/src/actions/auth-actions/passwordResetActions.ts`
  `requestPasswordReset(email, userType)` `:40-234`. **CAVEAT:** filters `is_inactive:false`
  `:68-75` → must reactivate (rollback) BEFORE calling, or the user is skipped.
  - reset URL `${baseUrl}/auth/reset-password?token=…`. Service: `PasswordResetService.ts`.

### Email infra (Resend)
- Temporal email service: `ee/temporal-workflows/src/services/email-service.ts`
  (`createEmailService`, singleton `emailService`; provider via `EMAIL_PROVIDER`/`RESEND_API_KEY`).
  Cancellation email activity `tenant-deletion-activities.ts:1774-1840` (`from:'info@nineminds.com'`).
- App/auth branded mail: `getAuthEmailRegistry()` (used in passwordResetActions).

### First-month discount (to be skipped on reactivation)
- nm-store `app/(frontend)/actions/stripe.ts` passes an `introCouponId`; `utils/stripe.ts`
  `resolveCheckoutDiscounts(couponId)` → `discounts:[{coupon}]`, plus optional `trial_period_days`.
  Reactivation checkout: pass coupon = null and no trial.

## Idempotency tie-in (this week's duplicate-tenant fix)

Reactivation MUST reattach the new subscription to the EXISTING tenant — it must NOT run the
normal create-tenant provisioning (that mints a new tenant). The new subscription has a fresh
`sub_…` id with no `tenant_id` metadata, so Layer 3 (metadata pre-check) would NOT short-circuit
and Layer 2 (no `stripe_subscriptions` row for the new sub id) would NOT block → the standard
order checkout WOULD create a duplicate tenant. Therefore reactivation runs a dedicated path,
not `ensureOrderInstallWorkflowForCheckoutSession`.

## Verified: confirmation timing vs. reactivation window (tenant-deletion-workflow.ts:347-391)

- After `confirmDeletion`, status → `confirmed`, `scheduled_deletion_date` overwritten to
  `now + deletionDelay` (30d/90d), then `await condition(() => rollbackSignal !== null,
  deletionDelay)` — **rollback is still accepted during the entire post-confirmation wait** (lines
  352-356). So `confirmed` IS reactivatable; the window just shrinks to the confirmed delay.
- Point of no return = status `deleting` (line 371), set only after the delay elapses with no
  rollback, immediately before `deleteTenantData()`.
- **`immediate` confirm** → `deletionDelay = 0` → the `if (deletionDelay > 0)` wait is skipped →
  `confirmed → deleting` back-to-back → **no reactivation window**.
- TWO date columns (RESOLVED — `updateDeletionStatus` + migration `20260113120000`):
  - `scheduled_deletion_date` NOT NULL = auto-delete deadline `canceled_at + 90d`, NEVER updated.
  - `deletion_scheduled_for` = confirmed actual date (e.g. `now + 30d`), NULL until `confirmDeletion`.
  - `updateDeletionStatus` writes `deletion_scheduled_for`, NOT `scheduled_deletion_date`.
  - Effective deletion date for emails/UI = `COALESCE(deletion_scheduled_for, scheduled_deletion_date)`.

## Detection (the query the helper wraps)

`pending_tenant_deletions` has `unique(['tenant'])` → at most one row per tenant. By email:
resolve email→tenant (check-tenant lookup), then:

```sql
SELECT deletion_id, status, workflow_id, workflow_run_id, canceled_at,
       scheduled_deletion_date, deletion_scheduled_for,
       COALESCE(deletion_scheduled_for, scheduled_deletion_date) AS effective_deletion_date,
       confirmation_type, trigger_source, subscription_external_id
FROM pending_tenant_deletions WHERE tenant = :tenantId;   -- 0 or 1 row
```

`reactivatable` = row exists AND `status IN ('pending','awaiting_confirmation','confirmed')`
(stricter than the existing `whereNotIn(['deleted','rolled_back','failed'])` in
start-deletion/route.ts — we also exclude `deleting`). Sub-states for messaging:
`awaiting_confirmation` = "waiting for confirmation" (show 90d auto date);
`confirmed` = "waiting for deletion date" (show `deletion_scheduled_for`).

## Resolved decisions (2026-06-01, user-confirmed)

- **IAP tenants: no reactivation** — no Stripe sub to re-create, no path back.
- **No refund machinery** for the point-of-no-return race (negligible probability); refuse + message.
- **Reactivation orchestration lives INSIDE the Temporal deletion workflow**, not a server handler.
  Rationale (user caught this): the `rollbackDeletion` signal is fire-and-forget and the actual
  reactivation runs asynchronously inside the still-running deletion workflow; a server handler
  would have to poll for `rolled_back`. Instead, extend the `rollbackDeletion` signal payload with
  an optional `reactivation` block `{ stripeCustomerId, stripeSubscriptionId, stripeSubscriptionItemId,
  stripePriceId, sendPasswordReset }`; the rollback handler (already durable/retried) does
  reactivate → link-subscription (new activity) → stamp metadata → password-reset (new activity).
  Server side = thin trigger that fires the enriched signal on checkout success. Admin rollback
  passes no reactivation block (back-compat).
  - New activities needed in the temporal worker: `linkSubscriptionToExistingTenant`,
    `triggerPasswordReset` (calls the password-reset service).
  - Signal payload type lives in `tenant-deletion-types.ts` (`RollbackDeletionSignal`).

## Review-2 fixes (2026-06-01, second pass)

1. **Charged-but-refused / no alerting gap (F034):** checkout→completion gap is minutes; if status
   crosses to `deleting` (immediate confirm, or 90d auto-delete landing then) Stripe already
   captured payment. Refuse path now fires an ops alert flagging the payment for MANUAL refund (no
   auto-refund). Don't pair "refuse + message" with silence.
2. **Double-payment idempotency (F022):** key on "tenant already has an active linked subscription",
   NOT the sub id — two real payments = two distinct `sub_…`. Also: once `rolled_back` the deletion
   workflow is CLOSED → signaling it throws; the trigger (F016) must detect closed/already-reactivated
   and route to F034 instead of signaling.
3. **Password reset from worker (F021→F035):** `requestPasswordReset` builds the link from
   `NEXT_PUBLIC_BASE_URL||NEXTAUTH_URL||HOST` (app env) and uses `getAuthEmailRegistry` (branded,
   app). The temporal worker is a separate deployment without those + a different Resend sender —
   it CANNOT mint a correct link. Resolution: worker activity calls an app-side HMAC endpoint that
   runs `requestPasswordReset` in app context. (Verified: passwordResetActions.ts:182-183.)
4. **Citus routing (F019):** tenant-scoped inserts from outside the normal path have bitten before
   (memory: insert routing can't be trigger-fixed). `createTenantInDB` ALREADY inserts
   stripe_customers/stripe_subscriptions from the worker with `tenant` set explicitly — that is the
   proven path. linkSubscriptionToExistingTenant must REUSE that exact insert code (shared helper),
   not hand-roll, so shard placement is identical. Test T058 asserts rows land under the tenant.
5. **Naming (F023/§9):** real nm-store symbols are `ensureOrderInstallWorkflowForCheckoutSession`
   (orderInstallFromCheckoutSession.ts) → `startOrderInstallWorkflow` (orderInstallTrigger.ts), plus
   `buildOrderInstallWorkflowInputFromCheckoutSession` / `isCheckoutSessionReadyForProvisioning` /
   `buildOrderInstallWorkflowId`. The not-called spy (T035) targets `startOrderInstallWorkflow`.
6. **Win-back recipient (F025):** detection keys on `user.tenant`; email goes to the tenant
   billing/admin email (not the attempter); per-tenant throttle is shared across users. By design.

## Review-3 fixes (2026-06-01, third pass — polish + 1 substantive)

- **Stale prose scrub:** §2 Goals + §11 acceptance criteria still said "correct-password" login —
  contradicted §8/decision-5. Scrubbed to "login attempt (password not verified)".
- **T006 field name:** aligned to `effectiveDeletionDate`/`deletionStatus` (was `scheduledDeletionDate`).
- **F034 sink made concrete (was hand-wavy "emit an alert"):** durable row in NEW
  `pending_reactivation_refunds` (F036, migration group) + email a monitored ops/billing inbox via
  the existing email service. Row = work queue, email = nudge. Avoids degrading to an unwatched log.
- **Stripe customer reconciliation (substantive — was missing):** the existing tenant already has a
  `stripe_customers` row from the original sub. createTenantInDB INSERTS a customer → blindly
  reusing it would create a DUPLICATE/divergent customer for the tenant (billing portal + webhooks
  key off it). Fix: (F037) reactivation checkout is created with the tenant's EXISTING `cus_…`
  (Stripe keeps the customer after `customer.subscription.deleted`); (F019) link reuses the existing
  `stripe_customers` row (match on tenant) and inserts ONLY the new `stripe_subscriptions` row;
  fall back to create only if no customer row exists. Idempotency was keyed on the subscription;
  the customer record is now explicitly covered too.

## Review-4: authorization model (2026-06-01) — who may reactivate

Question raised: a non-admin login attempt triggers the email — how do we accept their
confirmation / ensure billing authority? Answer (now §12, F038/F039):
- **Authority anchor = control of the tenant billing/admin email.** Can't use login/RBAC (all users
  are `is_inactive`). Same anchor Stripe + password-reset already use.
- **Recipient (F038):** email ALWAYS to the tenant billing/admin email (resolved server-side),
  NEVER the attempter or the order-form-entered email. A non-admin's attempt nudges the admin.
  nm-store never sees the admin address (anti-enumeration).
- **Token (F039):** signed, single-use, expiring, bound to tenant_id, in the email link; the
  reactivation checkout can't be created without it; consumed on success. Payment ≠ authority.
- **Access (F021):** force password-reset to the same admin inbox → payment alone grants no access.
- Chain: admin-inbox → token → checkout → payment → reset(to inbox) → access. Random payer w/o token
  can't initiate (blocks griefing/resurrection + enumeration); inbox-compromise = already-admin.
- v1 = single billing/admin email is the authority; finer billing-RBAC deferred.

## Review-5 fixes (2026-06-05)

1. **Single-use token needs durable state:** F039 now depends on F040
   `tenant_reactivation_tokens` with `token_hash`, `tenant`, `deletion_id`, `expires_at`,
   `reserved_at`, `consumed_at`, `checkout_session_id`, and timestamps. A signed token alone can
   expire but cannot enforce single-use; checkout creation must atomically reserve the row before
   creating Stripe Checkout, and completion consumes it.
2. **Stripe webhook branch made explicit:** F041 requires `checkout.session.completed` to branch on
   `session.metadata.reactivation === "true"` before normal `handleCheckoutCompleted` subscription
   import/update behavior. Reactivation sessions go to the reactivation trigger/guard path only.
3. **Stale refund wording scrubbed:** F032 no longer says refund policy is an open question; charged
   but refused payments route to F034 (ledger + ops/billing email, manual refund).
4. **Edition placement (F042) — `pending_tenant_deletions` is EE-only.** VERIFIED: the table is created
   solely by `ee/server/migrations/20260113120000_create_pending_tenant_deletions.cjs` (exact name
   `pending_tenant_deletions`, `createTable('pending_tenant_deletions')`). But check-tenant lives in
   **CE** at `server/src/app/api/billing/check-tenant/route.ts`, and the login hook is in **shared**
   `packages/auth`. Reading an EE-only table from CE/shared code throws where the table is absent.
   Move the HMAC endpoints (check-tenant + request-reactivation F006 + reactivation-password-reset
   F035) under `ee/server/src/app/api/...` (mirroring `internal/`, `provisioning/`,
   `v1/tenant-management/`), keeping the same HMAC URL paths nm-store calls. EE routes resolve via
   aliases (`scripts/build-enterprise.sh:23` "EE code resolved via aliases"; no filesystem overlay).
   Any pending-deletion read reachable in CE must fail-soft (table-absent ⇒ no pending deletion).
5. **Login hook via the EE injection pattern (F043).** VERIFIED pattern: `nextAuthOptions.ts` already
   lazy-loads EE impls through `loadEnterpriseSsoProviderRegistryImpl()` (`sso/enterpriseRegistryEntry.ts`,
   `@enterprise/*` dynamic import that resolves to a CE stub) behind `isEnterprise` +
   `enterpriseSsoRegistryInitPromise`. Do the same for the win-back hook — DON'T inline the
   `pending_tenant_deletions` query in `packages/auth/src/actions/auth.tsx`. Shared auth just calls the
   (no-op in CE) hook at the `is_inactive` gate (`auth.tsx:87`) and returns null as today.
6. **nm-store gets `cus_…` from Stripe, not alga's DB (F044) — answers "comes from stripe".** VERIFIED:
   nm-store's `createCheckoutSession`/`createTieredCheckoutSession` (`packages/nm-store/src/utils/stripe.ts`)
   pass **no** `customer` field today → Stripe mints a new customer each checkout. nm-store holds
   `STRIPE_SECRET_KEY` (`utils/stripe.ts:8`). Resolution: alga's token-exchange (F014/F039) returns a
   NON-PII Stripe id (the prior `subscription_external_id`, and/or `cus_…` read server-side from
   `stripe_customers` by tenant); nm-store sets `customer: cus_…` directly or derives it via
   `subscriptions.retrieve(sub_…).customer`. The admin EMAIL never crosses to nm-store (preserves F038).
   F037 updated: it does NOT ship alga's `stripe_customers` row across the boundary.
7. **Reactivated-but-unbilled partial failure (F045).** `handleRollback` sets status `rolled_back` +
   reactivates users at the TOP, then (new steps) links the sub + resets password. If
   `linkSubscriptionToExistingTenant` permanently fails after users are active and payment captured,
   the tenant is live with no linked subscription — uncovered by F034's existing reasons. On exhausted
   retries, raise F034 with a distinct `reactivated_unbilled` reason (durable row + email). Temporal
   activity retries cover transient failures first.
8. **F019 "reuse exact insert path" is a refactor, not a literal call (F046).** VERIFIED in
   `tenant-operations.ts`: customer insert (`:142-147`, `tenant`, `stripe_customer_external_id`,
   `billing_tenant: MASTER_TENANT_ID`) and subscription insert (`:221-222`) are coupled — the sub's
   `stripe_customer_id` FK uses the just-inserted internal customer (`:191`). Extract a shared helper
   that takes an EXISTING internal `stripe_customer_id` and inserts ONLY the sub row with `tenant` +
   `billing_tenant = MASTER_TENANT_ID`; createTenantInDB calls the same helper (no behavior change).
9. **Throttle atomicity (F047) + admin-email source of truth (F048).** (a) F026 must be a conditional
   `UPDATE ... WHERE last_winback_email_at IS NULL OR < now()-14d RETURNING`, emailing only when a row
   comes back — a read-check-update double-sends under concurrent attempts. (b) The whole authority
   model rests on resolving the billing/admin email; F048 pins the canonical field + fallback order
   (tenant owner/adminEmail → master-tenant client billing contact / Stripe customer email) behind one
   resolver used by both F008 and F025.

## Open questions / gotchas

- Win-back email throttle store: `last_winback_email_at` column on `pending_tenant_deletions`.
  Interval = **once per 14 days** (decided 2026-06-01), per login attempt.
- Anti-enumeration: checkout reactivation reveals account existence (user types their own
  email — acceptable). Win-back email is silent (no enumeration leak).
- Keep both `workflowClient.ts` copies in sync if a helper is added.

## Implementation log — request-reactivation group (2026-06-05)

- Implemented F006/F007/F008/F038/F039/F048 in alga EE:
  - `ee/server/src/app/api/billing/request-reactivation/route.ts` adds the HMAC
    `POST /api/billing/request-reactivation` endpoint at the same URL path nm-store signs.
    Missing/invalid signatures return 401; valid requests return `{ success: true }` without
    exposing tenant/admin details. Unknown, healthy, past-window, and unresolved-admin cases all
    return 200 with no email for anti-enumeration.
  - `ee/server/src/lib/billing/tenantReactivationTokens.ts` creates signed, expiring
    reactivation tokens and stores only `token_hash` in `tenant_reactivation_tokens`.
  - `ee/server/src/lib/billing/reactivationInviteEmail.ts` builds/sends the admin-inbox-only
    reactivation invite from `info@nineminds.com`; the email includes scheduled deletion date,
    standard-price/no-discount language, and a single checkout CTA.
  - `resolveBillingAdminEmailForTenant` documents the canonical authority resolver and fallback
    order: `tenants.email` -> master-tenant client `billing_email` -> `stripe_customers.email` ->
    first internal user email. Both request-reactivation and the future win-back hook should use it.
  - The request endpoint catches invite-send failures and still returns the anti-enumeration 200;
    delivery failures are logged without leaking state to nm-store.
- Implemented F009/F010/F011 in nm-store:
  - `requestTenantReactivation` signs and calls alga's request endpoint.
  - `requestReactivation(email)` server action wraps the utility.
  - `OrderForm` diverts `reactivatable:true` tenants to a Welcome back CTA and disables normal
    checkout; healthy existing tenants remain hard-blocked; past-window `deleting`/`deleted`
    tenants are allowed through normal signup.
- Tests completed:
  - Alga: T010-T013/T064/T065/T077 via route/helper/token contract tests.
  - nm-store: T014 via signed API utility test; T015-T018 via focused OrderForm reactivation tests.
- Commands:
  - `cd server && npm run test -- src/test/unit/billing/tenantReactivationDetection.test.ts src/test/unit/billing/tenantReactivationTokens.test.ts src/test/unit/api/billingCheckTenantReactivation.contract.test.ts src/test/unit/api/requestReactivation.contract.test.ts` (pass; existing coverage parse warnings only).
  - `cd ../nm-store/packages/nm-store && npm run test -- tests/unit/alga-api-tenant-reactivation.test.ts tests/unit/order-form-reactivation.test.tsx` (pass).

## Implementation log — reactivation-checkout group (2026-06-05)

- Implemented F014/F044 token exchange/reservation in alga EE:
  - `ee/server/src/app/api/billing/reactivation-token/route.ts` validates the signed token through
    HMAC service auth, atomically reserves the `tenant_reactivation_tokens` row, rechecks the
    pending deletion is still reactivatable, and returns only non-PII checkout context:
    tenant/deletion/workflow ids plus the existing Stripe `cus_...` when available. If no stored
    customer exists, it returns the prior `sub_...` so nm-store can derive the customer with Stripe.
  - `ee/server/src/app/api/billing/reactivation-token/session/route.ts` attaches the Stripe checkout
    session id to the reserved token ledger row. Added CE stubs and server re-exports for both paths.
  - `tenantReactivationTokens` now supports verify, reserve, checkout-session attachment, and
    consume-by-checkout-session helpers; replay is rejected once reserved or consumed.
- Implemented F012/F013/F037/F014/F015/F044 in nm-store:
  - `validateReactivationToken` and `recordReactivationCheckoutSession` sign calls to the alga token
    exchange/session routes; responses intentionally contain no admin email.
  - `createReactivationCheckoutSession` creates embedded Stripe Checkout with the standard
    recurring AlgaPSA monthly price, the existing Stripe customer, `reactivation:"true"` metadata,
    no `discounts`, and no `trial_period_days`.
  - `createTenantReactivationCheckout` validates/reserves the token, derives `cus_...` from a
    returned prior `sub_...` when needed, creates the Stripe session, then records the session id.
  - Added `/reactivate?token=...` and `/reactivation/success` pages. Success copy matches the PRD:
    "Your account is being restored" and "Check your email to set a new password."
- Tests completed:
  - T019-T024/T061/T066/T067/T073 via token ledger tests and nm-store reactivation checkout tests.
- Commands:
  - `cd server && npm run test -- src/test/unit/billing/tenantReactivationTokens.test.ts src/test/unit/billing/tenantReactivationDetection.test.ts` (pass; existing coverage parse warnings only).
  - `cd ../nm-store/packages/nm-store && npm run test -- tests/unit/reactivation-checkout.test.ts tests/unit/alga-api-tenant-reactivation.test.ts` (pass).

## Implementation log — reactivation-core group (2026-06-05)

- Implemented F016/F017/F018/F019/F020/F021/F022/F033/F034/F035/F041/F045/F046:
  - Extended `RollbackDeletionSignal` with an optional `reactivation` block while leaving the
    admin rollback route unchanged (no block passed).
  - `tenant-deletion-workflow.ts` now runs rollback in order: reactivate tenant users, remove the
    Canceled tag, reactivate the master client/contacts, then (for paid reactivation only) link the
    new Stripe subscription, stamp `subscription.metadata.tenant_id`, and trigger password reset.
  - Added `insertStripeSubscriptionForTenant` in `tenant-operations.ts` and refactored
    `createTenantInDB` onto it. `linkSubscriptionToExistingTenant` reuses the tenant's existing
    `stripe_customers` row, creates only the new `stripe_subscriptions` row, and blocks tenant-keyed
    duplicate active subscriptions.
  - Added HMAC `POST /api/billing/reactivation-password-reset` in EE so the worker calls the app
    context `requestPasswordReset(email,'internal')` after users are active.
  - Added HMAC `POST /api/billing/complete-reactivation` in EE to re-check pending-deletion state,
    send the enriched rollback signal, and route refused/closed/duplicate paid attempts into
    `pending_reactivation_refunds` plus an ops/billing email.
  - nm-store `reactivationCompletion.ts` retrieves the Stripe checkout session, extracts the sub/item
    and price ids, signs the completion call to alga, and `/reactivation/success` invokes it.
  - `ensureOrderInstallWorkflowForCheckoutSession` now branches `metadata.reactivation === "true"`
    before building/starting the normal order install workflow, so reactivation sessions cannot mint
    duplicate tenants.
- Tests completed:
  - Alga T027-T035/T051/T055-T058/T062/T063/T074/T075 via core contract tests and token tests.
  - nm-store T025/T027/T031/T035/T069/T070 via routing contract tests.
- Commands:
  - `cd server && npm run test -- src/test/unit/billing/reactivationCore.contract.test.ts src/test/unit/billing/tenantReactivationTokens.test.ts` (pass; existing coverage parse warnings only).
  - `cd ../nm-store/packages/nm-store && npm run test -- tests/unit/reactivation-core-routing.test.ts tests/unit/reactivation-checkout.test.ts` (pass).

## Implementation log — winback-login group (2026-06-05)

- Implemented F024/F025/F026/F027/F043/F047:
  - `packages/auth/src/actions/auth.tsx` now calls a fire-and-forget inactive-login win-back hook
    at the existing `user.is_inactive` gate and still immediately returns `null`. `verifyPassword`
    remains after the inactive gate, so the login attempt is not password-verified.
  - Added `packages/auth/src/lib/winback/enterpriseWinbackEntry.ts` using the existing
    `@enterprise/*` dynamic-import pattern. CE resolves to `packages/ee/src/lib/auth/loginWinback.ts`
    no-op stub; EE resolves to `ee/server/src/lib/auth/loginWinback.ts`.
  - EE hook performs a single conditional
    `UPDATE pending_tenant_deletions ... WHERE last_winback_email_at IS NULL OR < now()-14d
    RETURNING ...`; only the caller receiving a returned row sends email, making the throttle atomic.
  - Recipient is resolved through `resolveBillingAdminEmailForTenant`; the attempted user's email is
    never used as the destination. The hook mints a single-use token and sends the login-winback
    email via `sendLoginWinbackEmail`.
- Tests completed:
  - T036-T043/T059/T072/T076 via `loginWinback.contract.test.ts` plus token tests.
- Command:
  - `cd server && npm run test -- src/test/unit/billing/loginWinback.contract.test.ts src/test/unit/billing/tenantReactivationTokens.test.ts` (pass; existing coverage parse warnings only).

## Implementation log — emails group (2026-06-05)

- Completed F028/F029/F030:
  - Reactivation invite and login win-back templates live in
    `ee/server/src/lib/billing/reactivationInviteEmail.ts`.
  - Reactivation invite copy includes "Welcome back", the effective deletion date, a standard-price
    note, an explicit no-intro-discount/no-trial note, and one CTA to the token-gated checkout.
  - Login win-back copy includes the sign-in-attempt framing, effective deletion date, and the same
    reactivate CTA.
  - Both dispatch through the existing email-service interface from `info@nineminds.com` with
    `tenant_reactivation` metadata.
- Completed T044/T045/T046 in `server/src/test/unit/billing/reactivationEmails.test.ts`.
- Command:
  - `cd server && npm run test -- src/test/unit/billing/reactivationEmails.test.ts` (pass; existing
    coverage parse warnings only).

## Implementation log — regression group (2026-06-05)

- Completed F031/F032:
  - Added alga regression contract coverage in
    `server/src/test/unit/billing/reactivationRegression.contract.test.ts`.
  - Added nm-store regression routing coverage in
    `/Users/natalliabukhtsik/Desktop/projects/nm-store/packages/nm-store/tests/unit/reactivation-regression.test.ts`.
- Completed T047/T048:
  - Regression tests assert the paid reactivation path rolls back the existing tenant, links through
    `linkSubscriptionToExistingTenant`, triggers password reset, and keeps `linkSubscriptionToExistingTenant`
    / `insertStripeSubscriptionForTenant` away from tenant creation.
  - nm-store routing asserts reactivation sessions branch before
    `buildOrderInstallWorkflowInputFromCheckoutSession` / `startOrderInstallWorkflow`, and completion calls
    alga's `/api/billing/complete-reactivation`.
- Completed T049:
  - nm-store regression verifies past-window tenant checks (`pendingDeletion` with `deleting`/`deleted`)
    fall through as normal checkout instead of sending a reactivation email.
- Completed T050/T054:
  - alga regression verifies `deleting`/`deleted` are not active/reactivatable, completion refuses with
    the `past_window`/409 path, and the durable refund ledger is written.
- Completed T052/T053:
  - alga regression verifies `confirmed` remains reactivatable, workflow waits for rollback before
    entering `deleting`, `effectiveDeletionDate` coalesces `deletion_scheduled_for` over
    `scheduled_deletion_date`, and the email renders that date.
- Commands:
  - `cd server && npm run test -- src/test/unit/billing/reactivationRegression.contract.test.ts src/test/unit/billing/tenantReactivationDetection.test.ts src/test/unit/billing/reactivationEmails.test.ts` (pass; existing coverage parse warnings only).
  - `cd /Users/natalliabukhtsik/Desktop/projects/nm-store/packages/nm-store && npm run test -- tests/unit/reactivation-regression.test.ts tests/unit/order-form-reactivation.test.tsx tests/unit/reactivation-core-routing.test.ts` (pass).

## Implementation log (2026-06-05)

- Completed F001: added EE migration `ee/server/migrations/20260605120000_add_tenant_reactivation_winback_tables.cjs`
  with nullable `pending_tenant_deletions.last_winback_email_at`. The migration checks table/column
  existence before altering so it is safe to rerun and safe to roll back on partially-applied DBs.
- Completed F036: same migration creates `pending_reactivation_refunds` with tenant, checkout/payment/subscription
  Stripe ids, reason, `created_at`, `resolved_at`, plus `resolved_at` and unresolved open-queue indexes. This
  gives F034 a durable manual-refund work queue.
- Completed F040: same migration creates `tenant_reactivation_tokens` with `token_hash` uniqueness, tenant/deletion
  lookup, reservation/consumption timestamps, checkout session id, timestamps, and an open unexpired-token index.
- Completed T001/T060/T068: added source-level migration contract tests in
  `server/src/test/unit/migrations/tenantReactivationWinbackMigration.test.ts` covering idempotent guards,
  required columns, uniqueness, and open queue/token indexes.
- Verification: `cd server && npm run test -- src/test/unit/migrations/tenantReactivationWinbackMigration.test.ts`
  passed (3 tests). Running `npx vitest run server/src/test/unit/migrations/tenantReactivationWinbackMigration.test.ts`
  from the repo root found no matching test files because the server Vitest config is workspace-scoped.
- Completed F002: added `ee/server/src/lib/billing/tenantReactivationDetection.ts` with
  `getActivePendingDeletion(tenantId, knex?)`. It returns only `pending`, `awaiting_confirmation`,
  and `confirmed` rows, coalesces `deletion_scheduled_for ?? scheduled_deletion_date`, and fail-softs
  `42P01`/missing-table errors to `null` for CE safety.
- Completed F003: same helper file adds `resolveTenantAndAdminEmailByEmail(email, knex?)`, preserving
  existing check-tenant lookup order: `tenants.email` first, then internal-admin user fallback.
- Completed F004/F042: moved the real pending-deletion-aware check-tenant handler to
  `ee/server/src/app/api/billing/check-tenant/route.ts`; `server/src/app/api/billing/check-tenant/route.ts`
  now routes through `@enterprise/app/api/billing/check-tenant/route`, and the CE stub in
  `packages/ee/src/app/api/billing/check-tenant/route.ts` returns legacy existence data with
  `pendingDeletion:false`/`reactivatable:false` without querying `pending_tenant_deletions`.
- Completed F005: in sibling repo `/Users/natalliabukhtsik/Desktop/projects/nm-store`, updated
  `packages/nm-store/src/utils/alga-api.ts` and
  `packages/nm-store/src/app/(frontend)/actions/email-validation.ts` to surface
  `pendingDeletion`, `reactivatable`, `deletionStatus`, and `effectiveDeletionDate`; fail-open paths
  now explicitly return not-reactivatable.
- Completed T002/T003/T004/T005/T006/T007/T008/T071: added alga tests
  `server/src/test/unit/billing/tenantReactivationDetection.test.ts` and
  `server/src/test/unit/api/billingCheckTenantReactivation.contract.test.ts`.
- Completed T009: added nm-store test
  `/Users/natalliabukhtsik/Desktop/projects/nm-store/packages/nm-store/tests/unit/alga-api-tenant-reactivation.test.ts`.
- Verification: `cd server && npm run test -- src/test/unit/billing/tenantReactivationDetection.test.ts src/test/unit/api/billingCheckTenantReactivation.contract.test.ts`
  passed (7 tests). `cd /Users/natalliabukhtsik/Desktop/projects/nm-store/packages/nm-store &&
  npm run test -- tests/unit/alga-api-tenant-reactivation.test.ts` passed (2 tests).