feat: emit user_creation and tenant_disassociation lifecycle events

[supertokens-agent-runner]

Problem

PLAN-010 unit 1 (issue #1374) wired lifecycle events at the count-affecting
mutation points that were already transactional in core (user_deletion /
user_group_deletion on AuthRecipe.deleteUser, tenant_association on
Multitenancy.addUserIdToTenant). Two points were deferred because they
needed connection-taking storage variants that didn't exist yet: user_creation
(the recipe sign-up paths don't own the insert transaction) and
tenant_disassociation (Multitenancy.removeUserIdFromTenant wasn't
transactional at all).

Those storage variants have since landed on feat/activity-log
(plugin-interface #217, core in-memory #1399, postgresql #393), so this issue
(#1397) completes the two deferred points.

Fix

All emits go through ActivityLogSQLStorage.startAuditedTransaction, so the
event and the mutation it records commit (or roll back) on the same connection.

• user_creation — the interactive sign-up paths now create the user with
  the connection-taking signUp_Transaction / createUser_Transaction
  variants and emit one user_creation event (carrying the tenant) inside the
  transaction. The user-id retry loop on DuplicateUserIdException stays
  outside the transaction, as specified:
  • EmailPassword.signUp (interactive) — also folds the fake-email pre-verify
    onto the same connection, so it no longer opens a raw transaction.
  • EmailPassword.createUserWithPasswordHash (password-hash import) — the
    create is audited; the duplicate-email password-update branch stays a
    separate (still-allowlisted) transaction.
  • ThirdParty.createThirdPartyUser (the sign-in-up create path).
  • Passwordless.createPasswordlessUser.
  • WebAuthN.signUp — the whole method was already one transaction, so this is
    a clean swap to startAuditedTransaction.
• tenant_disassociation — Multitenancy.removeUserIdFromTenant is
  rewritten around startAuditedTransaction: it locks the user, snapshots the
  group's before-presence, calls removeUserIdFromTenant_Transaction, and emits
  only when a mapping was actually removed (withoutAudit otherwise). The
  non-auth-recipe cleanup that precedes it is not count-affecting and stays a
  separate step, as specified.
• Added LifecycleAuditEvent.forUserCreation / forTenantDisassociation
  factory methods (the payload builders already existed).
• Retired @UnauditedTransaction on the two methods whose only raw
  transaction was the (now-audited) creation: EmailPassword.signUp and
  WebAuthN.signUp. The shrink-only baseline drops 57 → 55
  (AuditEnforcementBaselineTest).

Not included: bulk-import user_creation

The issue also asks for one user_creation per user created by the bulk-import
paths. I've left this out of this PR and want a decision before doing it,
because it isn't mechanical:

• A bulk-imported recipe user can be inserted into several tenants at once
  (loginMethod.tenantIds), whereas an interactive creation always happens in
  exactly one tenant (extra tenants come later as tenant_association events).
  "One event per created user" then undercounts a multi-tenant import by
  N-1 per user. The correct shape is either one user_creation for a primary
  tenant plus tenant_association for the rest, or one user_creation per
  tenant — a ledger-semantics call I don't want to guess.
• The bulk-import worker runs on a BulkImportProxySQLStorage with its own
  commit/rollback (commitTransactionForBulkImportProxyStorage), so it can't
  use the startAuditedTransaction combinator directly; events would have to be
  written via createActivityLogEntry_Transaction on the proxy connection
  inside processUsersImportSteps, and the batch create methods return void
  (no created-id list to iterate).

Consequences: on this branch, bulk-imported users currently have no
user_creation event, so the ledger is not yet complete for that path (the
shadow audit would flag it). Everything else is complete.

Tests

Added to LifecycleMutationEventTest (in-memory SQLite):

• user_creation: email-password sign-up, password-hash import, third-party
  sign-in-up (event on create only, not on subsequent sign-in), passwordless
  create — each asserts exactly one event, the correct recipe/group id, and the
  schema-valid payload tenant.
• tenant_disassociation: emits once with the group's before-presence and the
  tenant on a real removal; re-removal is a no-op that emits nothing; removing
  a user never associated with the tenant emits nothing.
• Updated AuditEnforcementBaselineTest baseline to 55.

Atomicity (event commits with the mutation, rolls back together) is provided
structurally by the shared startAuditedTransaction combinator, which has its
own coverage; I did not re-prove per-path rollback with injected failures.

Ran locally (in-memory, SQLite)

• LifecycleMutationEventTest + AuditEnforcementBaselineTest — 16/16 pass.
• Regression (no behaviour change): webauthn.CredentialRegisterFlowTest,
  passwordless.PasswordlessConsumeCodeTest, emailpassword.UserMigrationTest,
  multitenant.TestTenantUserAssociation,
  thirdparty.api.ThirdPartySignInUpAPITest4_0,
  emailpassword.api.SignUpAPITest5_0, accountlinking.EmailPasswordTests —
  34/34 pass.

Not verified locally

• The full suite and the Postgres/MySQL storage matrix (CI covers these; the
  heavy matrix is gated behind the run-tests label on PRs).
• Bulk-import path (deferred; see above).

Cross-SDK note

supertokens-node is the reference implementation; python/golang port its
semantics. This change is core-only and rides on the feat/activity-log
activity-log ledger, which has no node/python/golang analogue yet — no port is
implied by this PR.

Fixes #1397

[supertokens-agent-runner]

Solid, well-scoped completion of the two deferred PLAN-010 unit-1 emit points. The retry-outside / mutation-inside pattern is right (each DuplicateUserIdException retry opens a fresh startAuditedTransaction, so no aborted-connection reuse), folding the fake-email verify onto the same connection is a genuine atomicity improvement over the old split transaction, and the withoutAudit no-op paths in removeUserIdFromTenant are correctly justified. The deferral of bulk-import user_creation is consistent — I confirmed the bulk paths go through the batch methods (createMultipleUsersWithPasswordHash / createMultipleThirdPartyUsers / createPasswordlessUsers), not the single-user methods touched here, so no proxy-storage collision.

One concrete gap and one behavioural question below. The gap: WebAuthn is listed as a converted user_creation path in the PR body but has no test asserting it emits the event — every other creation path got one. Since this swaps a raw startTransaction for startAuditedTransaction and adds the emit inside the pre-existing retry loop, it's changed behaviour that should be pinned by a test like the other four. (I did not run the build/matrix; findings are from reading the diff against the surrounding code.)

[supertokens-agent-runner]

Re-review of 9da1fb3 — the follow-up commit resolves all three points from my previous pass and I found nothing new to block on.

• WebAuthn test — webAuthnSignUpEmitsUserCreation drives the real HTTP register flow via webauthn.Utils.registerUserWithCredentials (signature matches) and pins exactly one USER_CREATION row with the response's recipe id and public tenant. This was the one emit landing inside the pre-existing while(true) retry loop, so a dedicated assertion is the right call.
• Fake-email test — fakeEmailSignUpVerifiesAndEmitsUserCreation uses st-user@stfakeemail.supertokens.com, which Utils.isFakeEmail recognises, and asserts both halves of the moved path: the user comes out verified (the pre-verify folded onto the audited connection) and exactly one user_creation is emitted. Matches the atomicity claim in EmailPassword.signUp.
• Tenant-removal FK invariant — the added comment on the UserNotFoundForLockingException no-op branch spells out the invariant (an auth user's tenant mapping cannot exist without the user row) and the parity with addUserIdToTenant, which is the right justification for the unreachable-in-a-consistent-DB branch.
• CHANGELOG — now the one-liner the maintainer asked for.

readEvents filters on event_type across a fresh per-test process with a single created user, so the assertEquals(1, ...) counts are safe. I did not run the build/matrix; findings are from reading the diff against the surrounding code.

[tamassoltesz]

For the bulk import questions:
The event should be user_import, as we want it to be part of the user count, but not the last_active rollup. It should emit one user_import for one tenant and one association event for every one of the remaining tenants.

[supertokens-agent-runner]

Implemented in 7097d1a, following your decision.

Emit (bulk import): per imported user, one user_import for the first tenant it lands in, then one tenant_association for each remaining tenant — with the group's tenant presence built up incrementally so each association carries the correct before-list. Emitted through startAuditedTransaction on the bulk-import proxy's single held connection (whose commitTransaction is a no-op), so the events land atomically with the import at commitTransactionForBulkImportProxyStorage and roll back with it on failure, exactly like the interactive emit sites. One event set per group (primary/oldest login-method id), so a linked user imported into N tenants is counted once per tenant, not once per login method.

Counting vs. rollup: added a USER_IMPORT type (payload mirrors user_creation — tenant only). CountDeltaInterpreter folds it identically to user_creation (+1 in its tenant), so imports are part of the user count. The last-active rollup (RollupUserLastActive / rollupLastActiveFromActivityLog) reads only user_last_active and account_linking rows, so it already excludes every lifecycle type including user_import — an imported user is present but not active, as intended. CountShadowAudit picks the new type up automatically from the enum.

Tests: interpreter/payload unit coverage for the new type and for the exact emit sequence (LifecycleEventFoldTest, LifecycleEventPayloadTest, in-memory); and a Postgres-gated integration test (BulkImportLifecycleEventTest) asserting the emitted user_import (+ tenant_association for the multi-tenant case) — the bulk-import proxy path is unsupported on the in-memory db, so it runs on Postgres/MySQL CI. Ran the in-memory suites locally (green); the Postgres path runs in CI.

Updated the CHANGELOG bullet accordingly (dropped the "bulk-import user_creation not yet included" caveat).

[tamassoltesz]

The last-active rollup (RollupUserLastActive / rollupLastActiveFromActivityLog) reads only user_last_active and account_linking rows, so it already excludes every lifecycle type including user_import — an imported user is present but not active, as intended. CountShadowAudit picks the new type up automatically from the enum.

It would be great if no user_last_active event was ever written, rather the actual activity would be counted in the last active fold. Is it possible?

[tamassoltesz]

It would be great if no user_last_active event was ever written, rather the actual activity would be counted in the last active fold. Is it possible?

[supertokens-agent-runner]

Good question — but I think it lands on the wrong PR, and the encouraging part is that the design already works the way you're describing.

Scope of this PR. #1403 only adds the lifecycle events — user_creation, tenant_disassociation, user_import: the mandatory, in-transaction, count-affecting mutations. It writes no user_last_active event at all. The user_last_active activity event lives entirely in the last-active path (ActiveUsers.updateLastActive + the sign-in/refresh/sign-up API handlers + RollupUserLastActive), none of which this PR touches.

On "is it possible". In the current design user_last_active is already not written to the projection table directly on activity. ActiveUsers.updateLastActive only appends a throttled user_last_active event to activity_log and marks the storage dirty; the rollup cron (RollupUserLastActive) is the sole writer of the user_last_active projection and derives it by folding those events. So "the actual activity counted in the last-active fold" is exactly what happens today — the event is the fold's input, not a redundant second write. There's no direct-write to remove.

What can't be removed for free is the event itself. Sign-ins/refreshes/sign-ups have no other representation in the activity log, so the throttled user_last_active event is the only per-activity recency signal the fold has. Drop it and the fold would see only lifecycle events (creation / link / delete), which collapses "last active" to roughly "created/linked at". Making sign-in and refresh first-class event types the fold reads instead would just relocate the write — it's still one event per activity, only under a different name.

So there's nothing to change in this PR to satisfy that. If you'd like to reshape the last-active event model itself (e.g. a different activity-signal vocabulary the fold reads, or dropping the projection table and folding at read time), that's a change to the last-active rollup path rather than this lifecycle-emit unit — I'm happy to take it there, but I'd want your call on the target shape before re-architecting that path, since it's a behavioural decision with a read-latency / storage tradeoff. Want me to open a separate issue to track it?

[supertokens-agent-runner]

Re-review of the user_import follow-up (7097d1a) added since my last pass — the bulk-import point that was deferred, now implemented per the maintainer's decision. It's correct and well-scoped:

• Atomicity — emitBulkImportLifecycleEvents runs startAuditedTransaction on the same BulkImportProxySQLStorage, so its startTransaction reuses the proxy's single held connection and its commitTransaction is the proxy no-op. The events therefore land at commitTransactionForBulkImportProxyStorage and rewind on rollbackTransactionForBulkImportProxyStorage / rollbackToSavepoint, identical to the sibling steps (verifyCollectedEmailAddressesForUsers, roles, etc.). Verified against both callers of processUsersImportSteps: the single-user importUser path and the cron importPartition batch path.
• Count semantics — USER_IMPORT folds identically to USER_CREATION (+1 in its tenant) in CountDeltaInterpreter, and the per-group emit sequence (one user_import for the first tenant + one tenant_association per remaining tenant, with groupBefore built up incrementally) yields exactly +1 per distinct tenant. CountShadowAudit.LIFECYCLE_EVENT_TYPES is derived from LifecycleEventType.values(), so the new type is picked up by the exact-vs-fold reconcile automatically, and the last-active rollup query (event_type IN ('user_last_active','account_linking')) correctly excludes it. Payload serialize/parse/validate all handle the new case.
• Tests — LifecycleEventFoldTest pins the fold and the 3-tenant emit sequence; BulkImportLifecycleEventTest (Postgres-gated) asserts the single- and multi-tenant emits including the association's before-presence. Good coverage.

No blocking defects — event COMMENT. One minor coverage note inline. Separately, the maintainer's open question about not writing user_last_active events at all is a design thread on a different mechanism (this PR writes no user_last_active rows), so it doesn't gate this diff's correctness. Findings are from reading the diff against the surrounding code; I did not run the build/matrix.

[supertokens-agent-runner]

Re-review at cf0c4250.

The #1397-owned changes are unchanged and still sound. Diffing my last-reviewed commit (8b7e99dd) against this head, none of the actual issue-#1397 files moved — the user_creation / tenant_disassociation / user_import emit paths (EmailPassword, ThirdParty, Passwordless, WebAuthN, Multitenancy, BulkImport, auditlog/lifecycle/*) and their tests are byte-for-byte what I already reviewed as correct. No new defects there.

One thing to fix before this merges: the branch has absorbed two downstream stacked PRs. The only diff since 8b7e99dd is the merge commit cf0c4250 ("Merge pull request #1404 from supertokens/agent/issue-1378-ledger-fold") — a backwards merge that folds child branches into this parent. As a result PR #1403's diff now also carries, out of scope:

• ApproximateUserCount.java serve-from-fold rework (+152/-66) and ApproximateUserCountTest.java (+280) — that's #1404 / issue #1378 (ledger-fold).
• UsersCountAPI.java default-flip — that's #1405 / issue #1379.
• Two CHANGELOG bullets (allowApproximate ... serves the exact anchor plus a fold; From CDI 5.6 the default ... serves anchor + fold) belonging to those same two PRs.

That code is fine (it was reviewed on its own PRs), but merging #1403 as-is would land #1404 and #1405 into feat/activity-log under this PR, bypassing their own review sign-off and muddying the ledger of what #1397 changed. Recommend restoring the branch to 1397-only scope — reset to 8b7e99dd and let stack-sync re-derive the forward merges — before this goes in. Flagging rather than blocking since it reads as a stack-sync mis-merge rather than an authoring mistake.

Separately, the maintainer's open question ("no user_last_active event ever written, count activity in the last-active fold instead") is a design thread on a different mechanism — this PR writes no user_last_active rows — and the author has already answered it and offered a separate issue. It doesn't gate this diff. Findings are from reading the diff against the surrounding code; I did not run the build/matrix.

[supertokens-agent-runner]

Re-review at 8ce64d1e. The only change since my last pass (cf0c4250) is the cross-login-method bulk-import test linkedGroupSpanningLoginMethodsUnionsTenantsAcrossThem that @tamassoltesz asked for — no source moved. The test is correct and closes the gap the earlier two multi-tenant cases left (both reached the multi-tenant branch via a single login method carrying two tenantIds, so they never exercised the union across login methods). This one puts EP in public and TP in t1, and pins exactly one user_import (tenant public, group = primary EP id) plus one tenant_association (tenant t1, groupBefore=[public]) — which is precisely what distinctTenantIdsInOrder's order-preserving union produces, and a regression reading tenants off a single login method would drop the association. Constructor arg order (isVerified, isPrimary) and the $2a/BCRYPT placeholder match the existing BulkImportTestUtils convention. Like the sibling cases it's Postgres/MySQL-gated (early-returns on in-mem), so it runs in CI rather than the in-mem suite. No new blocking issues; the #1397 lifecycle-emit content remains as previously reviewed.