@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

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

@@ -268,7 +268,7 @@ export async function moveTransferGraph(args: {
     { entityName: rootEntityName, rowIds: [rootRowId] },
   ];
 
-  for (let round = 0; round < MAX_TRANSFER_DEPTH && pending.length > 0; round++) {
+  for (let round = 0; round <= MAX_TRANSFER_DEPTH && pending.length > 0; round++) {
     // Merged per type so an edge leaving a type runs once per round, not once
     // per edge that reached it.
     const discovered = new Map<string, string[]>();
@@ -330,25 +330,18 @@ export async function moveTransferGraph(args: {
       }
     }
 
-    pending = [...discovered].map(([entityName, rowIds]) => ({ entityName, rowIds }));
-  }
+    // The extra round past the limit is a probe: it only exists to find out
+    // whether rows still hang below the last allowed hop. Its moves are rolled
+    // back with the transaction when this throws.
+    const [strandedEntityName] = discovered.keys();
+    if (round === MAX_TRANSFER_DEPTH && strandedEntityName !== undefined) {
+      throw new UnprocessableError("transfer_graph_too_deep", {
+        i18nKey: "errors.tenantHandover.transferGraphTooDeep",
+        details: { entityName: strandedEntityName },
+      });
+    }
 
-  // The depth limit is a safety net, not a licence to move part of a graph: if
-  // rounds ran out while rows remain whose type still leads somewhere, the
-  // declaration reaches further than the mover does, and returning quietly
-  // would leave exactly the orphaned rows #3088 is about.
-  //
-  // Rounds count hops of both edge kinds, while the boot validator measures
-  // reference chains between transferable entities only. A graph that fills the
-  // limit with reference hops and then adds a parentRef child therefore boots
-  // clean and fails here instead — the residual the validator cannot see, and
-  // the reason this check has to exist rather than trusting boot alone.
-  const stranded = pending.find(({ entityName }) => (adjacency.get(entityName) ?? []).length > 0);
-  if (stranded !== undefined) {
-    throw new UnprocessableError("transfer_graph_too_deep", {
-      i18nKey: "errors.tenantHandover.transferGraphTooDeep",
-      details: { entityName: stranded.entityName },
-    });
+    pending = [...discovered].map(([entityName, rowIds]) => ({ entityName, rowIds }));
   }
 
   return movedCounts;

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",
     });
@@ -141,6 +153,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
           now,
           log: (message) => ctx.log?.warn(message),
           fileProviderResolver: ctx._fileProviderResolver,
+          searchAdapter: ctx.searchAdapter,
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
           actor: ctx.systemUser.id,
         });

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

@@ -14,20 +14,24 @@ import {
   VersionConflictError,
 } from "@cosmicdrift/kumiko-framework/event-store";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+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,
@@ -42,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 {
@@ -77,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;
@@ -216,15 +238,53 @@ 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;
   readonly tenantId: TenantId;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  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);
 
@@ -246,27 +306,53 @@ export async function runNextDestructionStage(args: {
     tenantId: args.tenantId,
     log: args.log,
     fileProviderResolver: args.fileProviderResolver,
+    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,
@@ -284,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 };
+    });
   }
 }
 
@@ -334,6 +408,7 @@ export async function runTenantDestructionSweep(args: {
   readonly now?: Temporal.Instant;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  readonly searchAdapter?: SearchAdapter;
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
@@ -380,6 +455,7 @@ export async function runTenantDestructionSweep(args: {
         tenantId: row.id as TenantId,
         log: args.log,
         fileProviderResolver: args.fileProviderResolver,
+        searchAdapter: args.searchAdapter,
         escapeHatchAuditSink: args.escapeHatchAuditSink,
         actor: args.actor,
       });