@cosmicdrift/kumiko-bundled-features 0.288.0 → 0.289.0

package/src/tenant-handover/move-entity-graph.ts

@@ -0,0 +1,228 @@
+// The actual ownership change (kumiko-framework#3035): raw SQL against the
+// event store + read-model tables, because moving a row across the tenant
+// boundary is exactly the kind of write the framework's entity write map
+// cannot express (it is single-tenant-scoped by design — that boundary is
+// the whole point of `assertTenantMatch`). This is the framework's OWN
+// declared operation, not a consumer's `acknowledgeCrossTenant` escape.
+//
+// Every statement here runs inside the calling write handler's own
+// transaction (HandlerContext.db is transaction-scoped for the handler's
+// full duration — confirmed by dispatch-batch.ts's runBatch: a write handler
+// returning writeFailure throws BatchRollback inside the wrapping
+// `transaction()` call, rolling back everything the handler already did).
+// `moveRootRow` — called as row-bound-grant's `commitAnchor` — is therefore
+// the ONLY statement that must itself combine the anchor-spend with the
+// first write (#3023's hard rule: a write issued after `ok: true` can lose
+// its work to a crash while the grant is already burned). Everything after
+// it rides the same transaction: if a later step throws (an undeclared
+// child entity, kumiko-framework#3035's named-error requirement), the WHOLE
+// transaction — root row included — rolls back, so a caller can safely
+// retry the same token after fixing the app's `transferable` declarations.
+
+import {
+  type DbRunner,
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { resolveChildCandidates } from "./transfer-graph";
+
+const FILE_REFS_TABLE = "file_refs";
+const EVENTS_TABLE = "kumiko_events";
+const SNAPSHOTS_TABLE = "kumiko_snapshots";
+
+// The commitAnchor statement itself: spends the anchor (WHERE tenant_id =
+// expected) AND performs the ownership write (SET tenant_id = destination)
+// in one UPDATE — see file header. Returns whether THIS caller won.
+export async function moveRootRow(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly rowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<boolean> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $2 ` +
+      `WHERE "${args.idCol}" = $1 AND "${args.tenantCol}" = $3 ` +
+      `RETURNING "${args.idCol}" AS id`,
+    [args.rowId, args.destinationTenantId, args.sourceTenantId],
+  );
+  return rows.length === 1;
+}
+
+async function moveEventHistory(args: {
+  readonly db: DbRunner;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<void> {
+  // skip: an empty id list has nothing to move — both callers already
+  // filter to a non-empty list before calling, this only guards a future
+  // caller that forgets to.
+  if (args.aggregateIds.length === 0) return;
+  await executeRawQuery(
+    args.db,
+    `UPDATE ${EVENTS_TABLE} SET tenant_id = $1 ` +
+      `WHERE tenant_id = $2 AND aggregate_type = $3 AND aggregate_id = ANY($4)`,
+    [args.destinationTenantId, args.sourceTenantId, args.aggregateType, args.aggregateIds],
+  );
+  // Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+  // dropped rather than rewritten, forcing a full replay from the just-moved
+  // events on next read instead of carrying the snapshot's own generation
+  // bookkeeping across the tenant boundary.
+  await executeRawQuery(
+    args.db,
+    `DELETE FROM ${SNAPSHOTS_TABLE} WHERE tenant_id = $1 AND aggregate_id = ANY($2)`,
+    [args.sourceTenantId, args.aggregateIds],
+  );
+}
+
+async function moveFileRefs(args: {
+  readonly db: DbRunner;
+  readonly entityType: string;
+  readonly entityIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<number> {
+  if (args.entityIds.length === 0) return 0;
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE ${FILE_REFS_TABLE} SET tenant_id = $1 ` +
+      `WHERE tenant_id = $2 AND entity_type = $3 AND entity_id = ANY($4) RETURNING id`,
+    [args.destinationTenantId, args.sourceTenantId, args.entityType, args.entityIds],
+  );
+  return rows.length;
+}
+
+// `idCol` is a `parentRef.entityIdField` — by convention a text column (see
+// tags' tag-assignment entity: "Host entity ids are uuid/text; 128 covers
+// uuid plus non-uuid text keys"), never enforced as a type. A future
+// uuid-typed entityIdField would need the same CASE-guarded comparison
+// parent-ref-clause.ts uses for reads, to avoid a 22P02 on a non-uuid value
+// instead of silently matching zero rows.
+async function moveChildRows(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly typeCol: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly pkCol: string;
+  readonly rootEntityType: string;
+  readonly rootRowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<readonly string[]> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $1 ` +
+      `WHERE "${args.typeCol}" = $2 AND "${args.idCol}" = $3 AND "${args.tenantCol}" = $4 ` +
+      `RETURNING "${args.pkCol}" AS id`,
+    [args.destinationTenantId, args.rootEntityType, args.rootRowId, args.sourceTenantId],
+  );
+  return rows.map((row) => row.id);
+}
+
+// Everything the root ownership write does NOT cover: the root's own event
+// history + attached files, plus every parentRef-linked child's rows, event
+// history, and attached files. Returns a count per moved entity name (the
+// write handler turns this into the audit entry) — `fileRef` is a single
+// pooled count across root + every child, since it is not itself part of the
+// declared transfer graph (see files-tenant-data's own handover coverage for
+// why file BYTES never move, only the fileRef row's ownership).
+export async function moveTransferGraph(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly rootEntityName: string;
+  readonly rootRowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<Readonly<Record<string, number>>> {
+  const { db, registry, rootEntityName, rootRowId, sourceTenantId, destinationTenantId } = args;
+  const movedCounts: Record<string, number> = { [rootEntityName]: 1 };
+  const trackFileMove = (count: number) => {
+    // skip: nothing moved (this entity had no attached files) — the audit
+    // payload should list `fileRef` only when a file actually moved, not a
+    // stray zero entry for every root/child that happens to have none.
+    if (count === 0) return;
+    movedCounts["fileRef"] = (movedCounts["fileRef"] ?? 0) + count;
+  };
+
+  await moveEventHistory({
+    db,
+    aggregateType: rootEntityName,
+    aggregateIds: [rootRowId],
+    sourceTenantId,
+    destinationTenantId,
+  });
+  trackFileMove(
+    await moveFileRefs({
+      db,
+      entityType: rootEntityName,
+      entityIds: [rootRowId],
+      sourceTenantId,
+      destinationTenantId,
+    }),
+  );
+
+  for (const candidate of resolveChildCandidates(registry, rootEntityName)) {
+    const parentRef = candidate.entity.parentRef;
+    if (!parentRef) continue; // resolveChildCandidates already filtered on this — narrows for TS
+    const table = entityTableFromRegistry(registry, candidate.entityName, candidate.entity);
+    const tableName = extractTableName(table);
+    const typeCol = physicalColumnName(table, parentRef.entityTypeField);
+    const idCol = physicalColumnName(table, parentRef.entityIdField);
+    const tenantCol = physicalColumnName(table, "tenantId");
+    const pkCol = physicalColumnName(table, "id");
+
+    const childIds = await moveChildRows({
+      db,
+      tableName,
+      typeCol,
+      idCol,
+      tenantCol,
+      pkCol,
+      rootEntityType: rootEntityName,
+      rootRowId,
+      sourceTenantId,
+      destinationTenantId,
+    });
+    if (childIds.length === 0) continue;
+
+    // Moved first, validated second — safe only because everything here
+    // shares the root UPDATE's transaction (see file header): throwing now
+    // rolls this move back together with the root's, not just this one.
+    if (candidate.entity.transferable !== true) {
+      throw new UnprocessableError("entity_not_transferable", {
+        i18nKey: "errors.tenantHandover.entityNotTransferable",
+        details: { entityName: candidate.entityName },
+      });
+    }
+
+    movedCounts[candidate.entityName] = childIds.length;
+    await moveEventHistory({
+      db,
+      aggregateType: candidate.entityName,
+      aggregateIds: childIds,
+      sourceTenantId,
+      destinationTenantId,
+    });
+    trackFileMove(
+      await moveFileRefs({
+        db,
+        entityType: candidate.entityName,
+        entityIds: childIds,
+        sourceTenantId,
+        destinationTenantId,
+      }),
+    );
+  }
+
+  return movedCounts;
+}

package/src/tenant-handover/transfer-graph.ts

@@ -0,0 +1,44 @@
+// Resolves the declared transfer graph for a root entity type: the root
+// itself, plus every registered entity whose `parentRef` can name it as a
+// host (kumiko-framework#3035, framework CLAUDE.md premise 4 — the graph
+// depth is read off the existing parentRef declaration, never a hand-
+// maintained per-app list). parentRef is one level deep by construction (the
+// boot validator at engine/boot-validator/parent-ref.ts rejects a host that
+// itself declares a parentRef), so this resolves in one registry pass.
+
+import type { EntityDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+export type TransferChildCandidate = {
+  readonly entityName: string;
+  readonly entity: EntityDefinition;
+};
+
+export function resolveTransferableRoot(
+  registry: Registry,
+  entityType: string,
+): EntityDefinition | undefined {
+  const entity = registry.getAllEntities().get(entityType);
+  return entity?.transferable === true ? entity : undefined;
+}
+
+// Broad on purpose: a candidate's `parentRef.allowedTypes` is a declaration
+// of which host TYPES it accepts, not proof any row of it currently points
+// at THIS root instance. The caller queries actual rows per candidate and
+// only enforces `transferable` on candidates that turn out to have matching
+// rows — narrowing here to "has rows" would need the very query the caller
+// is about to run anyway, and would make an unrelated candidate with
+// `allowedTypes: undefined` (any host) silently invisible instead of
+// query-checked.
+export function resolveChildCandidates(
+  registry: Registry,
+  rootEntityType: string,
+): readonly TransferChildCandidate[] {
+  const candidates: TransferChildCandidate[] = [];
+  for (const [entityName, entity] of registry.getAllEntities()) {
+    const parentRef = entity.parentRef;
+    if (!parentRef) continue;
+    if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(rootEntityType)) continue;
+    candidates.push({ entityName, entity });
+  }
+  return candidates;
+}

package/src/tenant-lifecycle/stages.ts

@@ -99,6 +99,8 @@ async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
       }),
       registry: ctx.registry,
       tenantId: ctx.tenantId,
+      fileProviderResolver: ctx.fileProviderResolver,
+      log: ctx.log,
     };
     await destroy(hookCtx);
   }

package/src/user-data-rights/__tests__/anonymous-deletion.integration.test.ts

@@ -179,18 +179,53 @@ describe("anonymous deletion flow", () => {
     expect(second.status).toBe(422);
     expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
 
-    // #354/2: der anonyme Endpoint gibt einen generischen reason zurück und
-    // leakt NICHT den konkreten User-Status (currentStatus), den ein
-    // Token-Inhaber sonst proben könnte.
+    // #354/2 + #3024: the anonymous endpoint returns the same generic reason
+    // for EVERY error path as an invalid token — since the grace-period
+    // transition now lives inside commitDeletion (the anchor spend), there is
+    // no separate res.ok branch left that could leak the concrete user status
+    // (currentStatus).
     const body = (await second.json()) as {
       error: { details?: { reason?: string } };
     };
-    expect(body.error.details?.reason).toBe("cannot_process_deletion");
+    expect(body.error.details?.reason).toBe("invalid_or_expired_token");
     const serialized = JSON.stringify(body.error);
     expect(serialized).not.toContain("currentStatus");
     expect(serialized).not.toContain(USER_STATUS.DeletionRequested);
   });
 
+  test("concurrent confirm-by-token (#3024): two simultaneous redemptions of the same token leave exactly one winner", async () => {
+    // Real concurrency case, real HTTP calls via setupTestStack, no sleep —
+    // the interleaving width varies between runs, hence 20 repetitions
+    // instead of a single run (probabilistic test).
+    for (let i = 0; i < 20; i++) {
+      await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+      await seedAlice();
+      verifyCalls.length = 0;
+      await stack.http.raw("POST", "/api/write", {
+        type: REQUEST_BY_EMAIL,
+        payload: { email: ALICE_EMAIL },
+      });
+      const token = tokenFromLastVerifyCall();
+
+      const [first, second] = await Promise.all([
+        stack.http.raw("POST", "/api/write", { type: CONFIRM_BY_TOKEN, payload: { token } }),
+        stack.http.raw("POST", "/api/write", { type: CONFIRM_BY_TOKEN, payload: { token } }),
+      ]);
+
+      expect([first.status, second.status].sort()).toEqual([200, 422]);
+      // Exactly ONE lifecycle transition: the row lands at DeletionRequested,
+      // not in a last-write-wins in-between state from two applied writes.
+      expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
+
+      const loser = first.status === 422 ? first : second;
+      const body = (await loser.json()) as { error: { details?: { reason?: string } } };
+      expect(body.error.details?.reason).toBe("invalid_or_expired_token");
+      const serialized = JSON.stringify(body.error);
+      expect(serialized).not.toContain("currentStatus");
+      expect(serialized).not.toContain(USER_STATUS.DeletionRequested);
+    }
+  });
+
   test("replay-after-cancel (#354/1): Token nach cancel-deletion re-armt NICHT → 422, bleibt Active", async () => {
     await seedAlice();
     await stack.http.raw("POST", "/api/write", {

package/src/user-data-rights/__tests__/deletion-token-compat.test.ts

@@ -20,6 +20,7 @@ describe("deletion token wire format", () => {
       token: legacy,
       secret: SECRET,
       loadPendingRequestId: async () => REQUEST_ID,
+      commitDeletion: async () => true,
     });
 
     expect(result.ok).toBe(true);

package/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Deletion tokens are genuinely single-use, and a losing redeem no longer leaks status",
+    "detail": "`redeemDeletionToken` previously carried an `unsafeSkip` and a separate status check before the lifecycle write, so two concurrent redemptions of the same token could both get through. The lifecycle transition now rides the executor's `expect:` precondition inside the anchor spend, so exactly one redemption wins.\nExternally visible: the loser of a concurrent redeem now receives the same generic `invalid_or_expired_token` reason on the anonymous path as an unknown token, instead of `cannot_process_deletion`. That was the point — the old reason distinguished \"known token, wrong state\" from \"unknown token\" to an unauthenticated caller. Integrators matching on the old string on that endpoint should expect the generic one.\n`pendingDeletionRequestId` is now cleared on confirm as well, closing a pre-existing gap. `skipOptimisticLock: true` stays in the lifecycle path and now carries the reason it is correct there: callers structurally never hold a row version to pass through."
+  },
   {
     "version": "0.287.0",
     "type": "improvement",

package/src/user-data-rights/deletion-token.ts

@@ -33,6 +33,14 @@ export function redeemDeletionToken(args: {
   readonly token: string;
   readonly secret: string | undefined;
   readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
+  // Spends the anchor AND performs the actual lifecycle transition in one
+  // atomic step (#3024) — the caller (confirm-deletion-by-token) folds the
+  // Active→DeletionRequested write itself in here via `updateUserLifecycle`'s
+  // `expect: { status: Active, pendingDeletionRequestId }`, so a write issued
+  // after `ok: true` can't lose its work to a crash while the grant is
+  // already burned (see shared/row-bound-grant.ts). Returns whether this
+  // caller was the one who moved the row on.
+  readonly commitDeletion: (userId: string, requestId: string) => Promise<boolean>;
   readonly now?: Temporal.Instant;
 }): Promise<RowBoundGrantResult> {
   return redeemRowBoundGrant({
@@ -40,17 +48,7 @@ export function redeemDeletionToken(args: {
     purpose: DELETION_REQUEST_PURPOSE,
     secret: args.secret,
     loadAnchor: args.loadPendingRequestId,
-    commitAnchor: {
-      unsafeSkip: {
-        reason:
-          "pendingDeletionRequestId may only be changed through updateUserLifecycle — a " +
-          "conditional UPDATE would bypass the user.updated event and lose the field on a " +
-          "projection rebuild (see update-user-lifecycle.ts). The concurrent-redeem window " +
-          "this leaves open predates row-bound grants: startDeletionGracePeriod already " +
-          "read-then-writes the Active check. Closing it needs an atomic lifecycle " +
-          "transition, which is its own change.",
-      },
-    },
+    commitAnchor: args.commitDeletion,
     now: args.now,
   });
 }

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -40,17 +40,23 @@ async function readPendingDeletionRequestId(
   }
 }
 
-// Anonymer Apex-Flow Schritt 2: Verify-Link-Target. Verifiziert das
-// HMAC-Token, extrahiert die userId und startet die Grace-Period über die
-// geteilte Logik.
+// Anonymous apex flow step 2: verify-link target. Verifies the HMAC token,
+// extracts the userId, and flips the grace period through the shared logic —
+// in ONE atomic step with the anchor spend (#3024): commitDeletion carries
+// the actual grace-period transition, so a crash after the spend can no
+// longer lose the write step.
 //
-// Replay-Schutz (#354/1): die requestId der Row ist Teil des Verify-Keys. Wir
-// lesen sie über die (unverifizierte, nur-Lookup) userId aus dem Token, lehnen
-// einen fehlenden Eintrag ab und verifizieren das Token gegen die CURRENT
-// requestId. Ein zweites Confirm auf einen noch-pending User trifft zudem
-// non-active → cannot_process_deletion. Nach einem cancel-deletion (status →
-// Active, pendingDeletionRequestId → null) schlägt ein nachgespieltes Token an
-// der genullten/erneuerten requestId fehl — kein re-arm mehr.
+// Replay protection (#354/1): the row's requestId is part of the verify key.
+// We read it via the (unverified, lookup-only) userId from the token, reject
+// a missing entry, and verify the token against the CURRENT requestId. After
+// a cancel-deletion (status → Active, pendingDeletionRequestId → null), a
+// replayed token fails against the nulled/renewed requestId — no re-arm.
+//
+// Concurrency (#3024): two simultaneous confirms of the same token both read
+// the same requestId and both verify the HMAC — commitDeletion spends the
+// anchor AND writes the transition atomically (expect: status===Active &&
+// pendingDeletionRequestId===requestId), so exactly one wins. The loser gets
+// the same generic 422 as an invalid token — no status leak (#354/2).
 export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByTokenOptions = {}) {
   return defineWriteHandler({
     name: "confirm-deletion-by-token",
@@ -66,16 +72,6 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     agent: { expose: false },
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      // The row's requestId is part of the verify key, so a token from a
-      // cancelled or superseded cycle fails. Every error path ends in the same
-      // generic 422.
-      const verified = await redeemDeletionToken({
-        token: event.payload.token,
-        secret: opts.deletionTokenSecret,
-        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
-      });
-      if (!verified.ok) return writeFailure(invalidToken());
-
       // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
       // the compliance-profile shape.
       const profile = (await ctx.queryAs(
@@ -83,26 +79,40 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
         "compliance-profiles:query:for-tenant",
         {},
       )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
-      const res = await startDeletionGracePeriod(
-        ctx,
-        verified.subject,
-        profile.profile.userRights.gracePeriod,
-        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
-      );
-      if (!res.ok) {
-        // Generischer 422 statt res.error: dieser Endpoint ist anonym-öffentlich,
-        // res.error trägt den konkreten User-Status (currentStatus aus
-        // user_not_in_active_state) und würde einem Token-Inhaber das Proben des
-        // Account-Status erlauben (#354/2). Der authentifizierte request-deletion-
-        // Pfad zeigt dem User legitim seinen eigenen Status.
-        return writeFailure(new UnprocessableError("cannot_process_deletion"));
-      }
+
+      let gracePeriodEndIso: string | undefined;
+
+      // The row's requestId is part of the verify key, so a token from a
+      // cancelled or superseded cycle fails. Every error path ends in the same
+      // generic 422 — commitDeletion folding the grace-period write into the
+      // anchor-spend means there's no separate res.ok branch left to leak a
+      // concrete status through.
+      const verified = await redeemDeletionToken({
+        token: event.payload.token,
+        secret: opts.deletionTokenSecret,
+        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
+        commitDeletion: async (userId, requestId) => {
+          const res = await startDeletionGracePeriod(
+            ctx,
+            userId,
+            profile.profile.userRights.gracePeriod,
+            ctx.db.unsafeRaw(
+              "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream",
+            ),
+            { pendingDeletionRequestId: requestId },
+          );
+          if (!res.ok) return false;
+          gracePeriodEndIso = res.gracePeriodEnd.toString();
+          return true;
+        },
+      });
+      if (!verified.ok || gracePeriodEndIso === undefined) return writeFailure(invalidToken());
 
       return {
         isSuccess: true as const,
         data: {
           status: USER_STATUS.DeletionRequested,
-          gracePeriodEnd: res.gracePeriodEnd.toString(),
+          gracePeriodEnd: gracePeriodEndIso,
         },
       };
     },

package/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -25,6 +25,25 @@ export type StartGracePeriodResult =
 //
 // The user row is tenant-agnostic (account-wide deletion), so it is read via
 // ctx.db.global(userTable); only the grace period duration is tenant-configured.
+// That read only supplies email/locale for the caller's notification — it is
+// NOT the transition's guard. The guard is `expect: { status: Active }` on
+// the lifecycle write itself (#3024): the executor re-checks it against a
+// fresh row right before writing, so a concurrent caller that already moved
+// the user off Active is rejected even though this read saw Active.
+//
+// `additionalExpect` lets a caller fold its own precondition into the SAME
+// atomic write — the confirm-by-token path uses it to spend a row-bound
+// grant's anchor (pendingDeletionRequestId) in the same statement that flips
+// status, per shared/row-bound-grant.ts's "write in the same statement that
+// spends the anchor" contract. The write also always clears
+// pendingDeletionRequestId: a request-by-email token is meant for one
+// confirm only, and leaving the id in place would let it re-arm later if
+// something ever moves the user back to Active without going through
+// cancel-deletion's explicit null (restrict/lift-restriction can't today,
+// since status is a single field and Restricted/DeletionRequested are
+// mutually exclusive — but nulling it here doesn't depend on that staying
+// true). No-op for the authenticated request-deletion path, which never set
+// a pendingDeletionRequestId to begin with.
 //
 // `gracePeriod` and `lifecycleRunner` are resolved by the caller: both
 // require an escalation (reading the tenant compliance profile, appending to
@@ -35,6 +54,7 @@ export async function startDeletionGracePeriod(
   userId: string,
   gracePeriod: DurationSpec,
   lifecycleRunner: DbRunner,
+  additionalExpect?: Readonly<Record<string, string | number | boolean | null>>,
 ): Promise<StartGracePeriodResult> {
   const userRow = await ctx.db
     .global(userTable)
@@ -47,7 +67,17 @@ export async function startDeletionGracePeriod(
       }),
     };
   }
-  if (userRow["status"] !== USER_STATUS.Active) {
+
+  const T = getTemporal();
+  const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
+
+  const { applied } = await updateUserLifecycle(
+    lifecycleRunner,
+    userId,
+    { status: USER_STATUS.DeletionRequested, gracePeriodEnd, pendingDeletionRequestId: null },
+    { expect: { status: USER_STATUS.Active, ...additionalExpect } },
+  );
+  if (!applied) {
     return {
       ok: false,
       error: new UnprocessableError("user_not_in_active_state", {
@@ -56,14 +86,6 @@ export async function startDeletionGracePeriod(
     };
   }
 
-  const T = getTemporal();
-  const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
-
-  await updateUserLifecycle(lifecycleRunner, userId, {
-    status: USER_STATUS.DeletionRequested,
-    gracePeriodEnd,
-  });
-
   return {
     ok: true,
     gracePeriodEnd,

package/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -21,30 +21,68 @@ import { USER_STATUS, userEntity, userTable } from "../../user";
 // kann abweichen).
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 
+export type UpdateUserLifecycleOptions = {
+  // Declarative "genau einmal"-precondition (#3024): the update only applies
+  // if the row still holds these field values at write time. Forwarded
+  // as-is to the executor's `expect:` — see event-store-executor-write.ts
+  // for the atomicity story. Omitted: behaves exactly as before (unconditional
+  // overwrite, skipOptimisticLock). Scalars only — see the executor's
+  // `expect:` doc for why (`!==` comparison, no object/Date/Instant values).
+  readonly expect?: Readonly<Record<string, string | number | boolean | null>>;
+};
+
 // `conn` is ctx.db.unsafeRaw(reason) (regular handlers) or the open tx
 // (forget-cleanup sub-tx) — keeps the event append atomic with the write.
+//
+// Returns `{ applied: false }` instead of throwing only when `options.expect`
+// was set AND the executor rejected the write because the precondition no
+// longer held (precondition_failed) or a concurrent writer won the race on
+// the same stream version (version_conflict) — both mean "someone else's
+// transition already landed", the expected outcome for a caller that opted
+// into `expect`. Any other failure, or a failure with no `expect` set (every
+// pre-#3024 caller), still throws — those callers never checked a return
+// value, so silently dropping their write would be silent data loss.
 export async function updateUserLifecycle(
   conn: DbRunner,
   userId: string,
   changes: Record<string, unknown>,
-): Promise<void> {
+  options?: UpdateUserLifecycleOptions,
+): Promise<{ readonly applied: boolean }> {
   // user ist systemStream (#497): der Executor-Choke-Point addressiert den
   // Stream immer auf SYSTEM_TENANT_ID — ein Rescope auf die row-tenant_id
   // waere wirkungslos. "system"-Mode, damit loadById auch Legacy-Rows findet,
   // deren tenant_id noch vor dem #762-Backfill-Rebuild steht.
+  // skipOptimisticLock stays true (kept correct, not just carried over): it
+  // was set from this function's very first version (#494) because every
+  // caller here is a server-side business transition (restrict/lift-
+  // restriction/grace-period/cancel/forget), never a client edit-conflict UI
+  // round-trip — none of them read-then-hold a row version to pass as
+  // `payload.version`, so the executor's version gate would reject every
+  // call outright without it (`update()` requires `payload.version` unless
+  // skipOptimisticLock is set). #3024 replaces the safety that decision gave
+  // up with the purpose-built `expect:` precondition above, checked fresh at
+  // write time — the mechanism now genuinely matches the caller's shape
+  // (a business-field guard) instead of a repurposed version check.
   const tenantDb = createTenantDb(conn, SYSTEM_TENANT_ID, "system");
   const result = await userExecutor.update(
     { id: userId, changes },
     createSystemUser(SYSTEM_TENANT_ID),
     tenantDb,
-    { skipOptimisticLock: true },
+    { skipOptimisticLock: true, ...(options?.expect && { expect: options.expect }) },
   );
 
-  if (!result.isSuccess) {
-    throw new InternalError({
-      message: `user lifecycle update failed for ${userId}: ${result.error.code}`,
-    });
+  if (result.isSuccess) return { applied: true };
+
+  if (
+    options?.expect &&
+    (result.error.code === "precondition_failed" || result.error.code === "version_conflict")
+  ) {
+    return { applied: false };
   }
+
+  throw new InternalError({
+    message: `user lifecycle update failed for ${userId}: ${result.error.code}`,
+  });
 }
 
 // #494 Bestandsdaten-Reconcile: Rows, deren Lifecycle-State der alte