@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

package/packages/bundled-features/src/tenant/invited-membership.ts

@@ -3,6 +3,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbRunner,
+  type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
@@ -23,7 +24,13 @@ export type InvitedMembershipOptions = {
   readonly userId: string;
   readonly tenantId: TenantId;
   readonly role: string;
-  readonly invitationIssuedAt: Temporal.Instant;
+  readonly invitation: InvitationIssuance;
+};
+
+export type InvitationIssuance = {
+  readonly membershipVersion: number | null;
+  readonly insertedAt: Temporal.Instant;
+  readonly modifiedAt: Temporal.Instant | null;
 };
 
 type MembershipRow = {
@@ -34,6 +41,21 @@ type MembershipRow = {
   readonly modifiedAt: Temporal.Instant | null;
 };
 
+const MEMBERSHIP_CREATED_VERSION = 1;
+
+// 0 = the user has no membership in the tenant yet.
+export async function membershipVersionOf(
+  db: Pick<TenantDb, "fetchOne">,
+  tenantId: string,
+  userId: string,
+): Promise<number> {
+  const membership = await db.fetchOne<{ readonly version: number }>(tenantMembershipsTable, {
+    tenantId,
+    userId,
+  });
+  return membership?.version ?? 0;
+}
+
 // Add-only, so unlike updateMemberRoles no session revoke or last-TenantAdmin check.
 // Read unfiltered: tenant:query:memberships hides disabled tenants.
 export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedMembershipOptions) {
@@ -54,7 +76,7 @@ export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedM
   }
 
   // A membership decision made after the invitation was issued wins over it.
-  if (isMembershipChangedAfter(existing, options.invitationIssuedAt)) {
+  if (isSupersededByMembership(existing, options.invitation)) {
     return writeFailure(invitationSupersededError());
   }
 
@@ -71,17 +93,28 @@ export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedM
   return grantedMembership(true, roles);
 }
 
-// Resend reuses the invitation row, so its last modification is the latest issuance.
-export function invitationIssuedAt(invitation: {
-  readonly insertedAt: Temporal.Instant;
-  readonly modifiedAt: Temporal.Instant | null;
-}): Temporal.Instant {
-  return invitation.modifiedAt ?? invitation.insertedAt;
-}
-
-function isMembershipChangedAfter(membership: MembershipRow, instant: Temporal.Instant): boolean {
+// The pinned version is the membership's version when the invitation was issued
+// (0 = none yet). A different version now means the membership was decided after
+// the invite. Pin 0: a membership that appeared afterwards is an additive grant
+// only while it is untouched since its creation (version 1). A role change bumps
+// the version above 1 and counts as a decision. A removal in between hard-deletes
+// the row and cancels the invitation (remove-member), so it never reaches this check.
+// Rows issued before the pin existed (null) fall back to wall-clock timestamps,
+// which can misjudge changes within the same millisecond but is all they carry.
+function isSupersededByMembership(
+  membership: MembershipRow,
+  invitation: InvitationIssuance,
+): boolean {
+  if (invitation.membershipVersion !== null) {
+    if (invitation.membershipVersion === 0) {
+      return membership.version > MEMBERSHIP_CREATED_VERSION;
+    }
+    return membership.version !== invitation.membershipVersion;
+  }
+  // Resend reuses the invitation row, so its last modification is the latest issuance.
+  const issuedAt = invitation.modifiedAt ?? invitation.insertedAt;
   const lastChangedAt = membership.modifiedAt ?? membership.insertedAt;
-  return Temporal.Instant.compare(lastChangedAt, instant) > 0;
+  return Temporal.Instant.compare(lastChangedAt, issuedAt) > 0;
 }
 
 function invitationSupersededError(): ConflictError {

package/packages/bundled-features/src/tenant-handover/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Reference fields can opt out of the handover with handover: \"stay\"; boot depth limit and mover share one graph definition",
+    "detail": "ReferenceFieldDef gains handover: \"stay\". An entity that should NOT travel with its host but points at it through a plain reference no longer blocks the claim with entity_not_transferable when that reference field carries handover: \"stay\": the edge is not walked, its rows stay in the source tenant, and the reference crosses the tenant boundary after the handover. Without the opt-out the behaviour is unchanged (entity_not_transferable at claim time). Migration: an entity that should NOT travel with its host: mark the reference field handover: \"stay\" (removing transferable alone does not help once rows exist, the claim still fails). The framework now exports one adjacency definition (resolveEntityTransferAdjacency, reference and parentRef edges, non-transferable intermediate nodes included, handover: \"stay\" respected) that the boot validator's depth limit and the tenant-handover mover both use. Consequence: the boot-time MAX_TRANSFER_DEPTH check now also counts parentRef edges and chains running through non-transferable entities, as the mover always did; a graph that was deeper than 5 hops only through such nodes now fails the boot instead of the claim."
+  },
   {
     "version": "0.353.0",
     "type": "fix",

package/packages/bundled-features/src/tenant-handover/transfer-graph.ts

@@ -4,18 +4,12 @@
 // the graph depth is read off the existing declarations, never a hand-
 // maintained per-app list).
 //
-// Two edge kinds carry a graph (#3088):
-//   - `parentRef`, the polymorphic join-row link (entityTypeField +
-//     entityIdField). One level deep by construction — the boot validator at
-//     engine/boot-validator/parent-ref.ts rejects a host that itself declares
-//     a parentRef.
-//   - a plain `reference` field, whose `entity` names its target directly.
-//     These nest freely.
-//
-// What comes out is static adjacency, not a walk: which edges lead away from
-// each type, read straight off the declarations. The mover drives the actual
-// traversal from the row ids it moves (#3131), because how deep a type sits
-// depends on the rows found, not on the schema alone.
+// The edge definition (parentRef + single-valued reference fields, minus
+// `handover: "stay"`) lives in the framework so the boot validator's depth
+// limit and the mover's traversal measure the same graph. What comes out is
+// static adjacency, not a walk: the mover drives the actual traversal from the
+// row ids it moves (#3131), because how deep a type sits depends on the rows
+// found, not on the schema alone.
 //
 // `transferable: true` stays the only gate on what actually moves, and it is
 // enforced by the caller against edges that turn out to have rows rather than
@@ -25,22 +19,16 @@
 
 import {
   type EntityDefinition,
-  parseRefTargetEntityName,
   type Registry,
+  resolveEntityTransferAdjacency,
+  type TransferAdjacency,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-export type TransferEdgeLink =
-  | { readonly kind: "parentRef"; readonly typeField: string; readonly idField: string }
-  | { readonly kind: "reference"; readonly field: string };
-
-export type TransferEdge = {
-  readonly entityName: string;
-  readonly entity: EntityDefinition;
-  /** The already-resolved type this edge hangs off — its moved row ids are
-   *  the parent ids the mover matches this edge's rows against. */
-  readonly parentEntityName: string;
-  readonly link: TransferEdgeLink;
-};
+export type {
+  TransferAdjacency,
+  TransferEdge,
+  TransferEdgeLink,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export function resolveTransferableRoot(
   registry: Registry,
@@ -50,79 +38,9 @@ export function resolveTransferableRoot(
   return entity?.transferable === true ? entity : undefined;
 }
 
-// A `multiple` reference stores a jsonb array rather than a single id column,
-// which the mover's `= ANY($ids)` match cannot address. The boot validator
-// (engine/boot-validator/transfer-graph.ts) rejects that combination up front,
-// so skipping it here can only ever hit an entity that is not transferable —
-// never a silent partial move.
-function referenceEdgesFrom(entityName: string, entity: EntityDefinition): readonly TransferEdge[] {
-  const edges: TransferEdge[] = [];
-  for (const [fieldName, field] of Object.entries(entity.fields)) {
-    if (field.type !== "reference") continue;
-    if (field.multiple === true) continue;
-    edges.push({
-      entityName,
-      entity,
-      parentEntityName: parseRefTargetEntityName(field.entity),
-      link: { kind: "reference", field: fieldName },
-    });
-  }
-  return edges;
-}
-
-// A parentRef names the types it accepts; without `allowedTypes` it accepts
-// any of them, so the edge is recorded against every registered type.
-function parentRefEdgesFrom(
-  entityName: string,
-  entity: EntityDefinition,
-  allEntityNames: readonly string[],
-): readonly TransferEdge[] {
-  const parentRef = entity.parentRef;
-  if (!parentRef) return [];
-  const link: TransferEdgeLink = {
-    kind: "parentRef",
-    typeField: parentRef.entityTypeField,
-    idField: parentRef.entityIdField,
-  };
-  return (parentRef.allowedTypes ?? allEntityNames).map((parentEntityName) => ({
-    entityName,
-    entity,
-    parentEntityName,
-    link,
-  }));
-}
-
-/** Outgoing edges per type: keyed by the type an edge hangs off, so the mover
- *  can ask "what hangs off the rows I just moved" for any type it reaches, at
- *  any depth, as often as it reaches it. */
-export type TransferAdjacency = ReadonlyMap<string, readonly TransferEdge[]>;
-
-// A type can legitimately be reached by more than one edge — `note.vehicleId`
-// and `note.campaignId` are distinct, and collapsing them by entity name would
-// leave one edge's rows behind, the silent partial move #3088 exists to end.
-// Both are kept here; the mover runs each against whatever parent ids it has.
 export function resolveTransferAdjacency(
   registry: Registry,
   rootEntityType: string,
 ): TransferAdjacency {
-  const entities = registry.getAllEntities();
-  const allEntityNames = [...entities.keys()];
-  const byParent = new Map<string, TransferEdge[]>();
-
-  for (const [entityName, entity] of entities) {
-    // skip: the root is never collected as someone else's descendant. A self
-    // reference would otherwise drag unrelated rows of the root's own type
-    // across the tenant boundary along with the one that was claimed.
-    if (entityName === rootEntityType) continue;
-    for (const edge of [
-      ...parentRefEdgesFrom(entityName, entity, allEntityNames),
-      ...referenceEdgesFrom(entityName, entity),
-    ]) {
-      const edges = byParent.get(edge.parentEntityName) ?? [];
-      edges.push(edge);
-      byParent.set(edge.parentEntityName, edges);
-    }
-  }
-
-  return byParent;
+  return resolveEntityTransferAdjacency(registry.getAllEntities(), rootEntityType);
 }

package/packages/bundled-features/src/tenant-lifecycle/boot-checks.ts

@@ -9,8 +9,11 @@ import {
   isTenantResourceExtensionHooks,
   type ResolvedPiiFlags,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { entitiesOf } from "../shared/index.js";
 
+const log = createFallbackLogger("kumiko:boot");
+
 // V4: tenantOwned-entity-without-hook gate. Mirrors user-data-rights' V3
 // (validateGdprPiiHookCoverage) but for EXT_TENANT_DATA. Registered as this
 // feature's own `r.bootCheck()` (#1314, moved off the framework-internal
@@ -77,3 +80,16 @@ export function validateTenantDestroyHookShapes(features: readonly FeatureDefini
     }
   }
 }
+
+// `files-tenant-data` is opt-in (files stays usable without tenant-lifecycle),
+// so a tenant-lifecycle app that mounts `files` but forgets it destroys the
+// tenant's fileRef rows and storage binaries never — only a warning, since
+// some apps legitimately handle file erasure themselves.
+export function warnIfFilesMountedWithoutTenantData(features: readonly FeatureDefinition[]): void {
+  const mounted = new Set(features.map((f) => f.name));
+  // skip: nothing to cover (no files) or already covered.
+  if (!mounted.has("files") || mounted.has("files-tenant-data")) return;
+  log.warn(
+    'feature "files" is mounted with "tenant-lifecycle" but "files-tenant-data" is not — tenant destroy will leave fileRef rows and stored file binaries behind. Mount createFilesTenantDataFeature() to cover them.',
+  );
+}

package/packages/bundled-features/src/tenant-lifecycle/changes.json

@@ -1,4 +1,26 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "tenant-lifecycle/testing exports runTenantDestructionSweep, seedDestroyingTenant and driveDestructionToCompletion"
+  },
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Tenant destroy stages resume partial progress next tick; hooks may return { done: false } and get deadlineAt; file hooks work in chunks",
+    "detail": "Tenant destroy stages resume partial progress in the next sweep tick instead of burning failed attempts\nA tenant with tens of thousands of files used to exhaust the stage's three attempts and leave the DSGVO destroy stuck. Destroy hooks (`destroyTenant`, EXT_TENANT_DATA `destroy`) may now return `{ done: false, processed }` and receive `deadlineAt` in their ctx; the runner records a `tenant-destruction-stage-progressed` event in the tenant stream and continues the stage next tick without counting a failed attempt. Hooks returning nothing stay valid. The `fileRef` row purge and the storage prefix wipe work in chunks against that deadline."
+  },
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Boot warns when files is mounted without files-tenant-data",
+    "detail": "files-tenant-data is opt-in, so an app with tenant-lifecycle and files that forgot it silently left fileRef rows and stored binaries behind on tenant destroy. tenant-lifecycle now logs a boot warning in that case. Action: mount createFilesTenantDataFeature(), or ignore the warning if the app erases files itself."
+  },
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Tenant destroy: a stage tick without progress counts as a failed attempt; done:false requires processed"
+  },
   {
     "version": "0.337.0",
     "type": "fix",

package/packages/bundled-features/src/tenant-lifecycle/constants.ts

@@ -11,6 +11,8 @@ export const TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT =
   "tenant-destruction-stage-started" as const;
 export const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT =
   "tenant-destruction-stage-succeeded" as const;
+export const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT =
+  "tenant-destruction-stage-progressed" as const;
 export const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT =
   "tenant-destruction-stage-failed" as const;
 export const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT =
@@ -26,6 +28,8 @@ export const TENANT_DESTRUCTION_STARTED_EVENT_QN =
   `${EVENT_PREFIX}${TENANT_DESTRUCTION_STARTED_EVENT_SHORT}` as const;
 export const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_QN =
   `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT}` as const;
+export const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_QN =
+  `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT}` as const;
 export const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_QN =
   `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT}` as const;
 export const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_QN =
@@ -54,3 +58,7 @@ export const TENANT_DESTRUCTION_STAGES = [
 ] as const;
 
 export type TenantDestructionStageName = (typeof TENANT_DESTRUCTION_STAGES)[number];
+
+// The sweep cron fires every minute with concurrency "skip", so a tick must
+// finish well inside that window or the next one is skipped.
+export const DESTRUCTION_STAGE_TICK_BUDGET_MS = 30_000;

package/packages/bundled-features/src/tenant-lifecycle/events.ts

@@ -23,6 +23,12 @@ export const tenantDestructionStageSucceededSchema = z.object({
   attempts: z.number().int().positive(),
 });
 
+export const tenantDestructionStageProgressedSchema = z.object({
+  stage: z.string().min(1),
+  attempts: z.number().int().positive(),
+  processed: z.number().int().nonnegative(),
+});
+
 export const tenantDestructionStageFailedSchema = z.object({
   stage: z.string().min(1),
   attempts: z.number().int().positive(),

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -9,7 +9,11 @@ import {
   type FeatureDefinition,
   type TenantLifecycleStatusPlugin,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { validateTenantDataHookCoverage, validateTenantDestroyHookShapes } from "./boot-checks.js";
+import {
+  validateTenantDataHookCoverage,
+  validateTenantDestroyHookShapes,
+  warnIfFilesMountedWithoutTenantData,
+} from "./boot-checks.js";
 import {
   DESTRUCTION_CANCELLED_EVENT_SHORT,
   DESTRUCTION_REQUESTED_EVENT_SHORT,
@@ -17,6 +21,7 @@ import {
   TENANT_DESTRUCTION_FAILED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
   TENANT_DESTRUCTION_STARTED_EVENT_SHORT,
@@ -28,6 +33,7 @@ import {
   tenantDestructionFailedSchema,
   tenantDestructionStageAbandonedSchema,
   tenantDestructionStageFailedSchema,
+  tenantDestructionStageProgressedSchema,
   tenantDestructionStageStartedSchema,
   tenantDestructionStageSucceededSchema,
   tenantDestructionStartedSchema,
@@ -78,6 +84,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
     // guard's "tenant-lifecycle mounted" gate exactly.
     r.bootCheck(({ features }) => validateTenantDataHookCoverage(features));
     r.bootCheck(({ features }) => validateTenantDestroyHookShapes(features));
+    r.bootCheck(({ features }) => warnIfFilesMountedWithoutTenantData(features));
 
     r.defineEvent(DESTRUCTION_REQUESTED_EVENT_SHORT, destructionRequestedSchema, {
       piiFields: "none",
@@ -100,6 +107,11 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
       tenantDestructionStageSucceededSchema,
       { piiFields: "none" },
     );
+    r.defineEvent(
+      TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT,
+      tenantDestructionStageProgressedSchema,
+      { piiFields: "none" },
+    );
     r.defineEvent(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT, tenantDestructionStageFailedSchema, {
       piiFields: "none",
     });

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -18,17 +18,20 @@ import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantTable } from "../tenant/index.js";
 import {
+  DESTRUCTION_STAGE_TICK_BUDGET_MS,
   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_PROGRESSED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT,
   TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
   TENANT_DESTRUCTION_STARTED_EVENT_SHORT,
 } from "./constants.js";
 import { invalidateTenantLifecycleGate, TEARDOWN_GATE_SETTLE_MS } from "./lifecycle-gate.js";
 import {
+  type DestructionStage,
   type DestructionStageCtx,
   isDestructionPipelineComplete,
   pickNextStage,
@@ -43,6 +46,7 @@ type StageEventName =
   | 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_PROGRESSED_EVENT_SHORT
   | typeof TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT;
 
 function qualified(short: StageEventName): string {
@@ -78,6 +82,23 @@ function replayStageState(
   return { completed, abandoned, attemptsByStage };
 }
 
+// A progressed event as the stage's latest lifecycle event means the previous
+// tick handed over mid-stage; its stage-started is still the open one.
+function isStageContinuation(
+  events: ReadonlyArray<{ type: string; payload: Record<string, unknown> }>,
+  stageName: string,
+): boolean {
+  const stageEventTypes = new Set([
+    qualified(TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT),
+    qualified(TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT),
+    qualified(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT),
+  ]);
+  const lastStageEvent = events.findLast(
+    (event) => stageEventTypes.has(event.type) && event.payload["stage"] === stageName,
+  );
+  return lastStageEvent?.type === qualified(TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT);
+}
+
 function lastEventVersion(events: ReadonlyArray<{ version: number }>): number {
   const last = events.at(-1);
   return last?.version ?? 0;
@@ -217,6 +238,43 @@ async function maybeAppendDestructionCompleted(
   );
 }
 
+type StageTickResult = {
+  readonly done: boolean;
+  readonly error?: string;
+  readonly halted?: boolean;
+  readonly progressed?: boolean;
+};
+
+// `version` differs per caller: the catch path appends against the pre-run
+// version, the no-progress path against the version reloaded after run().
+async function recordFailedStageAttempt(args: {
+  readonly db: DbRunner;
+  readonly tenantId: TenantId;
+  readonly stage: DestructionStage;
+  readonly attempt: number;
+  readonly error: string;
+  readonly version: number;
+}): Promise<StageTickResult> {
+  if (args.attempt >= args.stage.maxAttempts) {
+    await haltPipelineOnAbandon({
+      db: args.db,
+      tenantId: args.tenantId,
+      stage: args.stage.name,
+      attempts: args.attempt,
+      error: args.error,
+    });
+    return { done: false, error: args.error, halted: true };
+  }
+  await appendTenantStageEvent(
+    args.db,
+    args.tenantId,
+    qualified(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT),
+    { stage: args.stage.name, attempts: args.attempt, error: args.error },
+    args.version,
+  );
+  return { done: false, error: args.error };
+}
+
 export async function runNextDestructionStage(args: {
   readonly db: DbRunner;
   readonly registry: Registry;
@@ -226,7 +284,7 @@ export async function runNextDestructionStage(args: {
   readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
-}): Promise<{ readonly done: boolean; readonly error?: string; readonly halted?: boolean }> {
+}): Promise<StageTickResult> {
   const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
   const { completed, abandoned, attemptsByStage } = replayStageState(events);
 
@@ -251,25 +309,50 @@ export async function runNextDestructionStage(args: {
     searchAdapter: args.searchAdapter,
     escapeHatchAuditSink: args.escapeHatchAuditSink,
     actor: args.actor,
+    deadlineAt: Date.now() + DESTRUCTION_STAGE_TICK_BUDGET_MS,
   };
 
   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),
-  );
+  if (!isStageContinuation(events, next.name)) {
+    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);
+    const outcome = 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);
+    // A tick that neither finishes nor processes anything would otherwise loop
+    // forever, because progressed events do not count as attempts.
+    if (!outcome.done && outcome.processed === 0) {
+      return await recordFailedStageAttempt({
+        db: args.db,
+        tenantId: args.tenantId,
+        stage: next,
+        attempt,
+        error: `stage "${next.name}" made no progress`,
+        version: lastEventVersion(eventsAfterRun),
+      });
+    }
+    if (!outcome.done) {
+      await appendTenantStageEvent(
+        args.db,
+        args.tenantId,
+        qualified(TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT),
+        { stage: next.name, attempts: attempt, processed: outcome.processed },
+        lastEventVersion(eventsAfterRun),
+      );
+      return { done: false, progressed: true };
+    }
     version = await appendTenantStageEventIdempotent(
       args.db,
       args.tenantId,
@@ -287,26 +370,14 @@ export async function runNextDestructionStage(args: {
     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 },
+    return await recordFailedStageAttempt({
+      db: args.db,
+      tenantId: args.tenantId,
+      stage: next,
+      attempt,
+      error: err instanceof Error ? err.message : String(err),
       version,
-    );
-    return { done: false, error: message };
+    });
   }
 }