@cosmicdrift/kumiko-bundled-features 0.125.2 → 0.127.0

package/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -0,0 +1,81 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant";
+import { DESTRUCTION_CANCELLED_EVENT_QN } from "../constants";
+import { invalidateTenantLifecycleGate } from "../lifecycle-gate";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+type TenantLifecycleRow = {
+  status: TenantLifecycleStatus;
+  gracePeriodEnd: Temporal.Instant | null;
+};
+
+export const cancelDestructionWrite = defineWriteHandler({
+  name: "cancel-destruction",
+  schema: z.object({}),
+  access: { roles: ["TenantOwner", "Admin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });
+    if (!row) {
+      return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
+    }
+    if (row.status !== "destroyRequested") {
+      return writeFailure(
+        new UnprocessableError("no_pending_destruction", {
+          details: { status: row.status },
+        }),
+      );
+    }
+
+    const gracePeriodEnd = row.gracePeriodEnd;
+    const inGrace =
+      gracePeriodEnd != null &&
+      Temporal.Instant.compare(gracePeriodEnd, getTemporal().Now.instant()) > 0;
+    if (!inGrace) {
+      return writeFailure(
+        new UnprocessableError("grace_period_expired", {
+          details: { reason: "grace_period_expired" },
+        }),
+      );
+    }
+
+    const update = await crud.update(
+      {
+        id: tenantId,
+        changes: {
+          status: "active",
+          destroyRequestedAt: null,
+          destroyRequestedBy: null,
+          gracePeriodEnd: null,
+        },
+      },
+      event.user,
+      ctx.db,
+      { skipOptimisticLock: true },
+    );
+    if (!update.isSuccess) return update;
+    invalidateTenantLifecycleGate(tenantId);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: tenantId,
+      aggregateType: "tenant",
+      type: DESTRUCTION_CANCELLED_EVENT_QN,
+      payload: { cancelledBy: event.user.id },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        tenantId,
+        status: "active" as const,
+        gracePeriodEnd: null as string | null,
+      },
+    };
+  },
+});

package/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -0,0 +1,83 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+import { resolveProfileForTenant } from "../../compliance-profiles";
+import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant";
+import { DESTRUCTION_REQUESTED_EVENT_QN } from "../constants";
+import { revokeTenantSessions } from "../lib/revoke-tenant-sessions";
+import { invalidateTenantLifecycleGate } from "../lifecycle-gate";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+type TenantLifecycleRow = {
+  status: TenantLifecycleStatus;
+  gracePeriodEnd: Temporal.Instant | null;
+};
+
+export const requestDestructionWrite = defineWriteHandler({
+  name: "request-destruction",
+  schema: z.object({}),
+  access: { roles: ["TenantOwner", "Admin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });
+    if (!row) {
+      return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
+    }
+    if (row.status !== "active") {
+      return writeFailure(
+        new UnprocessableError("tenant_not_active", {
+          details: { status: row.status },
+        }),
+      );
+    }
+
+    const { profile } = await resolveProfileForTenant({ db: ctx.db.raw, tenantId });
+    const T = getTemporal();
+    const gracePeriodEnd = addDurationSpec(T.Now.instant(), profile.tenantDestroyGracePeriod);
+
+    const update = await crud.update(
+      {
+        id: tenantId,
+        changes: {
+          status: "destroyRequested",
+          destroyRequestedAt: T.Now.instant(),
+          destroyRequestedBy: event.user.id,
+          gracePeriodEnd,
+        },
+      },
+      event.user,
+      ctx.db,
+      { skipOptimisticLock: true },
+    );
+    if (!update.isSuccess) return update;
+    invalidateTenantLifecycleGate(tenantId);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: tenantId,
+      aggregateType: "tenant",
+      type: DESTRUCTION_REQUESTED_EVENT_QN,
+      payload: {
+        requestedBy: event.user.id,
+        gracePeriodEnd: gracePeriodEnd.toString(),
+      },
+    });
+
+    if (ctx.hasFeature("sessions")) {
+      await revokeTenantSessions(ctx.db.raw, tenantId);
+    }
+
+    return {
+      isSuccess: true as const,
+      data: {
+        tenantId,
+        status: "destroyRequested" as const,
+        gracePeriodEnd: gracePeriodEnd.toString(),
+      },
+    };
+  },
+});

package/src/tenant-lifecycle/index.ts

@@ -0,0 +1,7 @@
+export {
+  TENANT_DESTRUCTION_STAGES,
+  TENANT_LIFECYCLE_FEATURE,
+  TenantLifecycleHandlers,
+} from "./constants";
+export { createTenantLifecycleFeature } from "./feature";
+export { resolveTenantLifecycleGate } from "./run-tenant-destroy";

package/src/tenant-lifecycle/lib/revoke-tenant-sessions.ts

@@ -0,0 +1,16 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { userSessionTable } from "../../sessions";
+
+/** Revoke all live sessions scoped to a tenant (destruction-request gate). */
+export async function revokeTenantSessions(db: DbRunner, tenantId: TenantId): Promise<number> {
+  const updated = await updateMany(
+    db,
+    userSessionTable,
+    { revokedAt: getTemporal().Now.instant() },
+    { tenantId, revokedAt: null },
+  );
+  return updated.length;
+}

package/src/tenant-lifecycle/lifecycle-gate.ts

@@ -0,0 +1,58 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { tenantTable } from "../tenant";
+
+export type TenantLifecycleGate = {
+  readonly status: string;
+  readonly gracePeriodEnd: string | null;
+};
+
+// Every authenticated + anonymous request consults this (via auth-middleware's
+// resolveTenantLifecycleStatus) — a per-request DB round-trip otherwise. No
+// TTL: status must be observable the instant it changes (a stale "active"
+// read after tombstoning would let a request slip through the 410 gate), so
+// this is invalidated explicitly by every status-changing write —
+// request/cancel-destruction, the sweep, and tombstoneTenantRow all call
+// invalidateTenantLifecycleGate(tenantId) right after their update succeeds.
+// Split into its own module (not run-tenant-destroy.ts) so stages.ts can
+// invalidate too without a stages.ts <-> run-tenant-destroy.ts import cycle.
+// ponytail: unbounded Map — fine while tenant counts stay in the thousands (a
+// few bytes/entry); swap for a bounded LRU if that ever changes.
+const gateCache = new Map<TenantId, TenantLifecycleGate | null>();
+
+export function invalidateTenantLifecycleGate(tenantId: TenantId): void {
+  gateCache.delete(tenantId);
+}
+
+/** @internal test-only — resetTestTables/resetTestTable wipe rows directly
+ *  via SQL, bypassing the write handlers that invalidate normally. Tests
+ *  that reset tenantTable (and reuse a fixed tenantId across cases) must
+ *  call this in beforeEach or a later test can read an earlier test's
+ *  cached status for the same tenantId. */
+export function resetTenantLifecycleGateCacheForTests(): void {
+  gateCache.clear();
+}
+
+export async function resolveTenantLifecycleGate(
+  db: DbRunner,
+  tenantId: TenantId,
+): Promise<TenantLifecycleGate | null> {
+  if (gateCache.has(tenantId)) return gateCache.get(tenantId) ?? null;
+  const rows = await selectMany<{ status: string; gracePeriodEnd: Temporal.Instant | null }>(
+    db,
+    tenantTable,
+    { id: tenantId },
+  );
+  const row = rows[0];
+  if (!row) {
+    gateCache.set(tenantId, null);
+    return null;
+  }
+  const gate: TenantLifecycleGate = {
+    status: row.status,
+    gracePeriodEnd: row.gracePeriodEnd?.toString() ?? null,
+  };
+  gateCache.set(tenantId, gate);
+  return gate;
+}

package/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -0,0 +1,368 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type Registry,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  append,
+  loadAggregate,
+  VersionConflictError,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { tenantEntity, tenantTable } from "../tenant";
+import {
+  TENANT_AGGREGATE_TYPE,
+  TENANT_DESTRUCTION_COMPLETED_EVENT_QN,
+  TENANT_DESTRUCTION_FAILED_EVENT_QN,
+  TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STARTED_EVENT_SHORT,
+} from "./constants";
+import { invalidateTenantLifecycleGate } from "./lifecycle-gate";
+import { type DestructionStageCtx, isDestructionPipelineComplete, pickNextStage } from "./stages";
+
+const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+const FEATURE_PREFIX = "tenant-lifecycle:event:";
+
+type StageEventName =
+  | typeof TENANT_DESTRUCTION_STARTED_EVENT_SHORT
+  | typeof TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT
+  | typeof TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT
+  | typeof TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT
+  | typeof TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT;
+
+function qualified(short: StageEventName): string {
+  return `${FEATURE_PREFIX}${short}`;
+}
+
+function replayStageState(
+  events: ReadonlyArray<{ type: string; payload: Record<string, unknown> }>,
+): {
+  completed: Set<string>;
+  abandoned: Set<string>;
+  attemptsByStage: Map<string, number>;
+} {
+  const completed = new Set<string>();
+  const abandoned = new Set<string>();
+  const attemptsByStage = new Map<string, number>();
+  for (const event of events) {
+    const payload = event.payload;
+    const stage = String(payload["stage"] ?? "");
+    if (event.type === qualified(TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT)) {
+      completed.add(stage);
+      continue;
+    }
+    if (event.type === qualified(TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT)) {
+      abandoned.add(stage);
+      continue;
+    }
+    if (event.type === qualified(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT)) {
+      const prev = attemptsByStage.get(stage) ?? 0;
+      attemptsByStage.set(stage, Math.max(prev, Number(payload["attempts"] ?? prev + 1)));
+    }
+  }
+  return { completed, abandoned, attemptsByStage };
+}
+
+function lastEventVersion(events: ReadonlyArray<{ version: number }>): number {
+  const last = events.at(-1);
+  return last?.version ?? 0;
+}
+
+function stageOutcomeRecorded(
+  events: ReadonlyArray<{ type: string; payload: Record<string, unknown> }>,
+  stageName: string,
+  outcomeShort:
+    | typeof TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT
+    | typeof TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT
+    | typeof TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT,
+): boolean {
+  return events.some(
+    (event) => event.type === qualified(outcomeShort) && event.payload["stage"] === stageName,
+  );
+}
+
+async function appendTenantStageEvent(
+  db: DbRunner,
+  tenantId: TenantId,
+  type: string,
+  payload: Record<string, unknown>,
+  expectedVersion: number,
+): Promise<void> {
+  await append(db, {
+    aggregateId: tenantId,
+    aggregateType: TENANT_AGGREGATE_TYPE,
+    tenantId,
+    expectedVersion,
+    type,
+    payload,
+    metadata: {
+      userId: "system",
+      requestId: `tenant-lifecycle:${type}`,
+    },
+  });
+}
+
+async function appendTenantStageEventIdempotent(
+  db: DbRunner,
+  tenantId: TenantId,
+  type: string,
+  payload: Record<string, unknown>,
+  expectedVersion: number,
+  alreadyRecorded: boolean,
+): Promise<number> {
+  if (alreadyRecorded) {
+    const events = await loadAggregate(db, tenantId, tenantId);
+    return lastEventVersion(events);
+  }
+  try {
+    await appendTenantStageEvent(db, tenantId, type, payload, expectedVersion);
+  } catch (err) {
+    if (!(err instanceof VersionConflictError)) throw err;
+    const events = await loadAggregate(db, tenantId, tenantId);
+    const stage = String(payload["stage"] ?? "");
+    if (stageOutcomeRecorded(events, stage, TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT)) {
+      // skip: idempotent retry — stage already recorded before version conflict
+      return lastEventVersion(events);
+    }
+    throw err;
+  }
+  const events = await loadAggregate(db, tenantId, tenantId);
+  return lastEventVersion(events);
+}
+
+async function markTenantDestroyFailed(db: DbRunner, tenantId: TenantId): Promise<void> {
+  const user = createSystemUser(tenantId);
+  const scopedDb = createTenantDb(db, tenantId, "system");
+  await tenantCrud.update(
+    {
+      id: tenantId,
+      changes: { status: "destroyFailed" },
+    },
+    user,
+    scopedDb,
+    { skipOptimisticLock: true },
+  );
+  invalidateTenantLifecycleGate(tenantId);
+}
+
+async function haltPipelineOnAbandon(args: {
+  readonly db: DbRunner;
+  readonly tenantId: TenantId;
+  readonly stage: string;
+  readonly attempts: number;
+  readonly error: string;
+}): Promise<void> {
+  const T = getTemporal();
+  const failedAt = T.Now.instant();
+  // Reload fresh instead of trusting a caller-supplied version: the failed
+  // stage's own run() may have appended to this same aggregate (e.g.
+  // tombstoneTenantRow's tenantCrud.update) before throwing, so any version
+  // captured earlier in the pipeline is stale and would VersionConflict here.
+  const eventsBeforeAbandon = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  await appendTenantStageEvent(
+    args.db,
+    args.tenantId,
+    qualified(TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT),
+    { stage: args.stage, attempts: args.attempts, error: args.error },
+    lastEventVersion(eventsBeforeAbandon),
+  );
+  const eventsAfterAbandon = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  const versionAfterAbandon = lastEventVersion(eventsAfterAbandon);
+  await appendTenantStageEvent(
+    args.db,
+    args.tenantId,
+    TENANT_DESTRUCTION_FAILED_EVENT_QN,
+    { stage: args.stage, error: args.error, failedAt: failedAt.toString() },
+    versionAfterAbandon,
+  );
+  await markTenantDestroyFailed(args.db, args.tenantId);
+}
+
+async function maybeAppendDestructionCompleted(
+  db: DbRunner,
+  tenantId: TenantId,
+  completed: ReadonlySet<string>,
+): Promise<void> {
+  if (!isDestructionPipelineComplete(completed)) {
+    // skip: pipeline still has pending stages
+    return;
+  }
+  const events = await loadAggregate(db, tenantId, tenantId);
+  if (events.some((event) => event.type === TENANT_DESTRUCTION_COMPLETED_EVENT_QN)) {
+    // skip: idempotent — completion event already recorded
+    return;
+  }
+  const T = getTemporal();
+  await appendTenantStageEvent(
+    db,
+    tenantId,
+    TENANT_DESTRUCTION_COMPLETED_EVENT_QN,
+    { destroyedAt: T.Now.instant().toString() },
+    lastEventVersion(events),
+  );
+}
+
+export async function runNextDestructionStage(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+  readonly log?: (message: string) => void;
+}): Promise<{ readonly done: boolean; readonly error?: string; readonly halted?: boolean }> {
+  const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
+  const { completed, abandoned, attemptsByStage } = replayStageState(events);
+
+  if (abandoned.size > 0) {
+    return { done: false, error: "pipeline_abandoned", halted: true };
+  }
+
+  const next = pickNextStage(completed, abandoned);
+  if (!next) {
+    await maybeAppendDestructionCompleted(args.db, args.tenantId, completed);
+    return { done: isDestructionPipelineComplete(completed) };
+  }
+
+  const priorAttempts = attemptsByStage.get(next.name) ?? 0;
+  const attempt = priorAttempts + 1;
+  const ctx: DestructionStageCtx = {
+    db: args.db,
+    registry: args.registry,
+    tenantId: args.tenantId,
+    log: args.log,
+  };
+
+  let version = lastEventVersion(events);
+  version = await appendTenantStageEventIdempotent(
+    args.db,
+    args.tenantId,
+    qualified(TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT),
+    { stage: next.name, attempts: attempt },
+    version,
+    stageOutcomeRecorded(events, next.name, TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT),
+  );
+
+  try {
+    await next.run(ctx);
+    // next.run() may itself have appended events to this aggregate (e.g.
+    // tombstoneTenantRow updates the tenant row on the same stream) — reload
+    // the version fresh instead of trusting the pre-run `version`, or this
+    // append throws VersionConflictError on every stage whose run() writes.
+    const eventsAfterRun = await loadAggregate(args.db, args.tenantId, args.tenantId);
+    version = await appendTenantStageEventIdempotent(
+      args.db,
+      args.tenantId,
+      qualified(TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT),
+      { stage: next.name, attempts: attempt },
+      lastEventVersion(eventsAfterRun),
+      stageOutcomeRecorded(
+        eventsAfterRun,
+        next.name,
+        TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
+      ),
+    );
+
+    const completedAfter = new Set([...completed, next.name]);
+    await maybeAppendDestructionCompleted(args.db, args.tenantId, completedAfter);
+    return { done: isDestructionPipelineComplete(completedAfter) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const isFinal = attempt >= next.maxAttempts;
+    if (isFinal) {
+      await haltPipelineOnAbandon({
+        db: args.db,
+        tenantId: args.tenantId,
+        stage: next.name,
+        attempts: attempt,
+        error: message,
+      });
+      return { done: false, error: message, halted: true };
+    }
+    await appendTenantStageEvent(
+      args.db,
+      args.tenantId,
+      qualified(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT),
+      { stage: next.name, attempts: attempt, error: message },
+      version,
+    );
+    return { done: false, error: message };
+  }
+}
+
+/** Cron entry: start destruction for tenants past grace, then advance stages. */
+export async function runTenantDestructionSweep(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly now?: Temporal.Instant;
+  readonly log?: (message: string) => void;
+}): Promise<{ readonly triggered: number; readonly advanced: number }> {
+  const T = getTemporal();
+  const now = args.now ?? T.Now.instant();
+  const due = await selectMany<{ id: string }>(args.db, tenantTable, {
+    status: "destroyRequested",
+    gracePeriodEnd: { lte: now },
+  });
+
+  let triggered = 0;
+  for (const row of due) {
+    const tenantId = row.id as TenantId;
+    const events = await loadAggregate(args.db, tenantId, tenantId);
+    const version = lastEventVersion(events);
+    const user = createSystemUser(tenantId);
+    const scopedDb = createTenantDb(args.db, tenantId, "system");
+    // Version-guarded (no skipOptimisticLock): a concurrent cancel-destruction
+    // between the `due` select above and this write also appends to the same
+    // tenant stream, so an unguarded overwrite here would silently revert the
+    // cancellation. A version conflict means we lost that race — skip, the
+    // tenant is no longer due and the next tick re-evaluates it.
+    const result = await tenantCrud.update(
+      { id: tenantId, version, changes: { status: "destroying", destroyStartedAt: now } },
+      user,
+      scopedDb,
+    );
+    if (!result.isSuccess) continue;
+    invalidateTenantLifecycleGate(tenantId);
+    await appendTenantStageEvent(
+      args.db,
+      tenantId,
+      qualified(TENANT_DESTRUCTION_STARTED_EVENT_SHORT),
+      { startedAt: now.toString() },
+      version + 1,
+    );
+    triggered++;
+  }
+
+  let advanced = 0;
+  const destroying = await selectMany<{ id: string }>(args.db, tenantTable, {
+    status: "destroying",
+  });
+  for (const row of destroying) {
+    try {
+      const result = await runNextDestructionStage({
+        db: args.db,
+        registry: args.registry,
+        tenantId: row.id as TenantId,
+        log: args.log,
+      });
+      if (!result.error && !result.halted) advanced++;
+    } catch (err) {
+      // Isolate the failure to this tenant — an uncaught throw here must not
+      // abort the whole sweep tick and starve every other "destroying" tenant
+      // of progress. The tenant stays "destroying" and the next tick retries.
+      args.log?.(
+        `[tenant-lifecycle] sweep: unexpected error advancing tenant ${row.id}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+
+  return { triggered, advanced };
+}
+
+export { invalidateTenantLifecycleGate, resolveTenantLifecycleGate } from "./lifecycle-gate";