@cosmicdrift/kumiko-bundled-features 0.353.0 → 0.354.0

package/dist/tenant/invited-membership.js

@@ -9,6 +9,15 @@ import { findForbiddenMembershipRole, reservedMembershipRoleError } from "./memb
 import { tenantMembershipEntity, tenantMembershipsTable } from "./membership-table.js";
 import { seedTenantMembership } from "./seeding.js";
 const membershipExecutor = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, { entityName: "tenant-membership" });
+const MEMBERSHIP_CREATED_VERSION = 1;
+// 0 = the user has no membership in the tenant yet.
+export async function membershipVersionOf(db, tenantId, userId) {
+    const membership = await db.fetchOne(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, options) {
@@ -28,7 +37,7 @@ export async function grantInvitedMembershipRole(db, options) {
         return grantedMembership(false, [options.role]);
     }
     // 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());
     }
     const currentRoles = parseRoles(existing.roles);
@@ -40,13 +49,25 @@ export async function grantInvitedMembershipRole(db, options) {
         return updateResult;
     return grantedMembership(true, roles);
 }
-// Resend reuses the invitation row, so its last modification is the latest issuance.
-export function invitationIssuedAt(invitation) {
-    return invitation.modifiedAt ?? invitation.insertedAt;
-}
-function isMembershipChangedAfter(membership, instant) {
+// 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, invitation) {
+    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() {
     return new ConflictError({

package/dist/tenant/schema/tenant.d.ts

@@ -69,6 +69,7 @@ export declare const tenantEntity: import("@cosmicdrift/kumiko-types/fields").En
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"active" | "destroyFailed" | "destroyRequested" | "destroyed" | "destroying">[] | undefined;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -224,6 +225,7 @@ export declare const tenantTable: import("@cosmicdrift/kumiko-framework/db").Ent
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"active" | "destroyFailed" | "destroyRequested" | "destroyed" | "destroying">[] | undefined;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };

package/dist/tenant-handover/transfer-graph.d.ts

@@ -1,23 +1,4 @@
-import { type EntityDefinition, type Registry } 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;
-};
+import { type EntityDefinition, type Registry, type TransferAdjacency } from "@cosmicdrift/kumiko-framework/engine";
+export type { TransferAdjacency, TransferEdge, TransferEdgeLink, } from "@cosmicdrift/kumiko-framework/engine";
 export declare function resolveTransferableRoot(registry: Registry, entityType: string): EntityDefinition | undefined;
-/** 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[]>;
 export declare function resolveTransferAdjacency(registry: Registry, rootEntityType: string): TransferAdjacency;

package/dist/tenant-handover/transfer-graph.js

@@ -4,90 +4,23 @@
 // 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
 // here: a declaration names which types an edge accepts, never proof that any
 // row currently travels it. Narrowing here would need the very query the caller
 // is about to run anyway.
-import { parseRefTargetEntityName, } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveEntityTransferAdjacency, } from "@cosmicdrift/kumiko-framework/engine";
 export function resolveTransferableRoot(registry, entityType) {
     const entity = registry.getAllEntities().get(entityType);
     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, entity) {
-    const edges = [];
-    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, entity, allEntityNames) {
-    const parentRef = entity.parentRef;
-    if (!parentRef)
-        return [];
-    const link = {
-        kind: "parentRef",
-        typeField: parentRef.entityTypeField,
-        idField: parentRef.entityIdField,
-    };
-    return (parentRef.allowedTypes ?? allEntityNames).map((parentEntityName) => ({
-        entityName,
-        entity,
-        parentEntityName,
-        link,
-    }));
-}
-// 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, rootEntityType) {
-    const entities = registry.getAllEntities();
-    const allEntityNames = [...entities.keys()];
-    const byParent = new Map();
-    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/dist/tenant-lifecycle/boot-checks.d.ts

@@ -1,3 +1,4 @@
 import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export declare function validateTenantDataHookCoverage(features: readonly FeatureDefinition[]): void;
 export declare function validateTenantDestroyHookShapes(features: readonly FeatureDefinition[]): void;
+export declare function warnIfFilesMountedWithoutTenantData(features: readonly FeatureDefinition[]): void;

package/dist/tenant-lifecycle/boot-checks.js

@@ -1,5 +1,7 @@
 import { EXT_EXTERNAL_RESOURCE, EXT_INFRA_RESOURCE, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, isTenantDataExtensionHooks, isTenantResourceExtensionHooks, } 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
@@ -60,3 +62,14 @@ export function validateTenantDestroyHookShapes(features) {
         }
     }
 }
+// `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) {
+    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/dist/tenant-lifecycle/constants.d.ts

@@ -5,6 +5,7 @@ export declare const DESTRUCTION_CANCELLED_EVENT_SHORT: "destruction-cancelled";
 export declare const TENANT_DESTRUCTION_STARTED_EVENT_SHORT: "tenant-destruction-started";
 export declare const TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT: "tenant-destruction-stage-started";
 export declare const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT: "tenant-destruction-stage-succeeded";
+export declare const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT: "tenant-destruction-stage-progressed";
 export declare const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT: "tenant-destruction-stage-failed";
 export declare const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT: "tenant-destruction-stage-abandoned";
 export declare const TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT: "tenant-destruction-completed";
@@ -13,6 +14,7 @@ export declare const DESTRUCTION_REQUESTED_EVENT_QN: "tenant-lifecycle:event:des
 export declare const DESTRUCTION_CANCELLED_EVENT_QN: "tenant-lifecycle:event:destruction-cancelled";
 export declare const TENANT_DESTRUCTION_STARTED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-started";
 export declare const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-stage-succeeded";
+export declare const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-stage-progressed";
 export declare const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-stage-failed";
 export declare const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-stage-abandoned";
 export declare const TENANT_DESTRUCTION_COMPLETED_EVENT_QN: "tenant-lifecycle:event:tenant-destruction-completed";
@@ -24,3 +26,4 @@ export declare const TenantLifecycleHandlers: {
 };
 export declare const TENANT_DESTRUCTION_STAGES: readonly ["external-resources", "search-indices", "cache", "app-data", "subject-keys", "files", "infra-resources", "tenant-row"];
 export type TenantDestructionStageName = (typeof TENANT_DESTRUCTION_STAGES)[number];
+export declare const DESTRUCTION_STAGE_TICK_BUDGET_MS = 30000;

package/dist/tenant-lifecycle/constants.js

@@ -6,6 +6,7 @@ export const DESTRUCTION_CANCELLED_EVENT_SHORT = "destruction-cancelled";
 export const TENANT_DESTRUCTION_STARTED_EVENT_SHORT = "tenant-destruction-started";
 export const TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT = "tenant-destruction-stage-started";
 export const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT = "tenant-destruction-stage-succeeded";
+export const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT = "tenant-destruction-stage-progressed";
 export const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT = "tenant-destruction-stage-failed";
 export const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT = "tenant-destruction-stage-abandoned";
 export const TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT = "tenant-destruction-completed";
@@ -14,6 +15,7 @@ export const DESTRUCTION_REQUESTED_EVENT_QN = `${EVENT_PREFIX}${DESTRUCTION_REQU
 export const DESTRUCTION_CANCELLED_EVENT_QN = `${EVENT_PREFIX}${DESTRUCTION_CANCELLED_EVENT_SHORT}`;
 export const TENANT_DESTRUCTION_STARTED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_STARTED_EVENT_SHORT}`;
 export const TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT}`;
+export const TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_PROGRESSED_EVENT_SHORT}`;
 export const TENANT_DESTRUCTION_STAGE_FAILED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT}`;
 export const TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT}`;
 export const TENANT_DESTRUCTION_COMPLETED_EVENT_QN = `${EVENT_PREFIX}${TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT}`;
@@ -33,3 +35,6 @@ export const TENANT_DESTRUCTION_STAGES = [
     "infra-resources",
     "tenant-row",
 ];
+// 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/dist/tenant-lifecycle/events.d.ts

@@ -17,6 +17,11 @@ export declare const tenantDestructionStageSucceededSchema: z.ZodObject<{
     stage: z.ZodString;
     attempts: z.ZodNumber;
 }, z.core.$strip>;
+export declare const tenantDestructionStageProgressedSchema: z.ZodObject<{
+    stage: z.ZodString;
+    attempts: z.ZodNumber;
+    processed: z.ZodNumber;
+}, z.core.$strip>;
 export declare const tenantDestructionStageFailedSchema: z.ZodObject<{
     stage: z.ZodString;
     attempts: z.ZodNumber;

package/dist/tenant-lifecycle/events.js

@@ -17,6 +17,11 @@ export const tenantDestructionStageSucceededSchema = z.object({
     stage: z.string().min(1),
     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/dist/tenant-lifecycle/feature.js

@@ -1,7 +1,7 @@
 import { defineFeature, EXT_EXTERNAL_RESOURCE, EXT_INFRA_RESOURCE, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, } from "@cosmicdrift/kumiko-framework/engine";
-import { validateTenantDataHookCoverage, validateTenantDestroyHookShapes } from "./boot-checks.js";
-import { DESTRUCTION_CANCELLED_EVENT_SHORT, DESTRUCTION_REQUESTED_EVENT_SHORT, TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT, TENANT_DESTRUCTION_FAILED_EVENT_SHORT, 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.js";
-import { destructionCancelledSchema, destructionRequestedSchema, tenantDestructionCompletedSchema, tenantDestructionFailedSchema, tenantDestructionStageAbandonedSchema, tenantDestructionStageFailedSchema, tenantDestructionStageStartedSchema, tenantDestructionStageSucceededSchema, tenantDestructionStartedSchema, } from "./events.js";
+import { validateTenantDataHookCoverage, validateTenantDestroyHookShapes, warnIfFilesMountedWithoutTenantData, } from "./boot-checks.js";
+import { DESTRUCTION_CANCELLED_EVENT_SHORT, DESTRUCTION_REQUESTED_EVENT_SHORT, TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT, 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, } from "./constants.js";
+import { destructionCancelledSchema, destructionRequestedSchema, tenantDestructionCompletedSchema, tenantDestructionFailedSchema, tenantDestructionStageAbandonedSchema, tenantDestructionStageFailedSchema, tenantDestructionStageProgressedSchema, tenantDestructionStageStartedSchema, tenantDestructionStageSucceededSchema, tenantDestructionStartedSchema, } from "./events.js";
 import { cancelDestructionWrite } from "./handlers/cancel-destruction.write.js";
 import { requestDestructionWrite } from "./handlers/request-destruction.write.js";
 import { hasTenantDestructionWork, resolveTenantLifecycleGate, runTenantDestructionSweep, } from "./run-tenant-destroy.js";
@@ -37,6 +37,7 @@ export function createTenantLifecycleFeature() {
         // 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",
         });
@@ -50,6 +51,7 @@ export function createTenantLifecycleFeature() {
             piiFields: "none",
         });
         r.defineEvent(TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT, 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/dist/tenant-lifecycle/run-tenant-destroy.d.ts

@@ -3,6 +3,12 @@ import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { type EscapeHatchAuditSink, type Registry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+type StageTickResult = {
+    readonly done: boolean;
+    readonly error?: string;
+    readonly halted?: boolean;
+    readonly progressed?: boolean;
+};
 export declare function runNextDestructionStage(args: {
     readonly db: DbRunner;
     readonly registry: Registry;
@@ -12,11 +18,7 @@ export declare function runNextDestructionStage(args: {
     readonly searchAdapter?: SearchAdapter;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly actor?: string;
-}): Promise<{
-    readonly done: boolean;
-    readonly error?: string;
-    readonly halted?: boolean;
-}>;
+}): Promise<StageTickResult>;
 export declare function hasTenantDestructionWork(reads: Pick<TenantDb, "count">, now: Temporal.Instant): Promise<boolean>;
 /** Cron entry: start destruction for tenants past grace, then advance stages. */
 export declare function runTenantDestructionSweep(args: {

package/dist/tenant-lifecycle/run-tenant-destroy.js

@@ -5,7 +5,7 @@ import { createSystemUser, } 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/index.js";
-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.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 { isDestructionPipelineComplete, pickNextStage, } from "./stages.js";
 const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
@@ -35,6 +35,17 @@ function replayStageState(events) {
     }
     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, stageName) {
+    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) {
     const last = events.at(-1);
     return last?.version ?? 0;
@@ -114,6 +125,22 @@ async function maybeAppendDestructionCompleted(db, tenantId, completed) {
     const T = getTemporal();
     await appendTenantStageEvent(db, tenantId, TENANT_DESTRUCTION_COMPLETED_EVENT_QN, { destroyedAt: T.Now.instant().toString() }, lastEventVersion(events));
 }
+// `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) {
+    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) {
     const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
     const { completed, abandoned, attemptsByStage } = replayStageState(events);
@@ -136,36 +163,49 @@ 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, 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 };
+        return await recordFailedStageAttempt({
+            db: args.db,
+            tenantId: args.tenantId,
+            stage: next,
+            attempt,
+            error: err instanceof Error ? err.message : String(err),
+            version,
+        });
     }
 }
 function destroyRequestedDueWhere(now) {

package/dist/tenant-lifecycle/stages.d.ts

@@ -12,11 +12,16 @@ export type DestructionStageCtx = {
     readonly searchAdapter?: SearchAdapter;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly actor?: string;
+    readonly deadlineAt: number;
+};
+export type StageRunOutcome = {
+    readonly done: boolean;
+    readonly processed: number;
 };
 export type DestructionStage = {
     readonly name: TenantDestructionStageName;
     readonly maxAttempts: number;
-    readonly run: (ctx: DestructionStageCtx) => Promise<void>;
+    readonly run: (ctx: DestructionStageCtx) => Promise<StageRunOutcome>;
 };
 export declare const DESTRUCTION_STAGES: readonly DestructionStage[];
 export declare function pickNextStage(completedStages: ReadonlySet<string>, abandonedStages: ReadonlySet<string>): DestructionStage | null;

package/dist/tenant-lifecycle/stages.js

@@ -7,21 +7,39 @@ import { purgeSearchDocumentsForSubject, } from "@cosmicdrift/kumiko-framework/s
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { tenantEntity, tenantMembershipEntity, tenantMembershipsTable, tenantTable, } from "../tenant/index.js";
 import { invalidateTenantLifecycleGate } from "./lifecycle-gate.js";
+const STAGE_DONE = { done: true, processed: 0 };
 const tenantCrud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
 const tenantMembershipCrud = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, {
     entityName: "tenant-membership",
 });
+// Every hook still runs each tick (they are idempotent), so a later hook is not
+// starved by an earlier one that keeps reporting done:false.
+function newOutcomeAccumulator() {
+    let allDone = true;
+    let processed = 0;
+    return {
+        add: (result) => {
+            if (result?.done === false)
+                allDone = false;
+            processed += result?.processed ?? 0;
+        },
+        outcome: () => ({ done: allDone, processed }),
+    };
+}
 async function runExtensionDestroyHooks(registry, extensionName, ctx) {
     const usages = registry.getExtensionUsages(extensionName);
+    const total = newOutcomeAccumulator();
     for (const usage of usages) {
         if (!isTenantResourceExtensionHooks(usage.options)) {
             throw new Error(`${extensionName} registration for "${usage.entityName}" has no destroy function`);
         }
-        await usage.options.destroyTenant(ctx.tenantId, ctx);
+        total.add(await usage.options.destroyTenant(ctx.tenantId, ctx));
     }
+    return total.outcome();
 }
 async function runTenantDataHooks(ctx) {
     const usages = ctx.registry.getExtensionUsages(EXT_TENANT_DATA);
+    const total = newOutcomeAccumulator();
     for (const usage of usages) {
         if (!isTenantDataExtensionHooks(usage.options)) {
             throw new Error(`${EXT_TENANT_DATA} registration for "${usage.entityName}" has no destroy function`);
@@ -41,18 +59,20 @@ async function runTenantDataHooks(ctx) {
             }),
             registry: ctx.registry,
             tenantId: ctx.tenantId,
+            deadlineAt: ctx.deadlineAt,
             fileProviderResolver: ctx.fileProviderResolver,
             log: ctx.log,
         };
-        await destroy(hookCtx);
+        total.add(await destroy(hookCtx));
     }
+    return total.outcome();
 }
 async function eraseSubjectKeys(ctx) {
     const kms = configuredPiiSubjectKms();
     if (!kms) {
         ctx.log?.("[tenant-lifecycle] subject-keys stage skipped: no KMS adapter configured");
         // skip: KMS optional — apps without crypto-shredding still run other destroy stages
-        return;
+        return STAGE_DONE;
     }
     const memberships = await selectMany(ctx.db, tenantMembershipsTable, {
         tenantId: ctx.tenantId,
@@ -72,11 +92,13 @@ async function eraseSubjectKeys(ctx) {
     if (ctx.searchAdapter) {
         await purgeSearchDocumentsForSubject(ctx.db, ctx.registry.features, ctx.searchAdapter, subjectIdToKey(tenantRecordSubject), tenantRecordSubject);
     }
+    return STAGE_DONE;
 }
 async function purgeTenantCache(ctx) {
     // ponytail: Redis SCAN+DEL is wired when ctx carries a redis client; until
     // then this stage is a documented no-op (no cache layer in test stack).
     ctx.log?.("[tenant-lifecycle] cache stage: no redis client in ctx — skipped");
+    return STAGE_DONE;
 }
 async function tombstoneTenantRow(ctx) {
     const now = getTemporal().Now.instant();
@@ -110,6 +132,7 @@ async function tombstoneTenantRow(ctx) {
         },
     }, user, db, { skipOptimisticLock: true });
     invalidateTenantLifecycleGate(ctx.tenantId);
+    return STAGE_DONE;
 }
 export const DESTRUCTION_STAGES = [
     {

package/dist/tenant-lifecycle/testing.d.ts

@@ -0,0 +1,8 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { runTenantDestructionSweep } from "./run-tenant-destroy.js";
+export declare function seedDestroyingTenant(db: DbConnection, tenantId: TenantId): Promise<void>;
+export declare function driveDestructionToCompletion(stack: TestStack, db: DbConnection, tenantId: TenantId, searchAdapter?: SearchAdapter): Promise<string>;
+export { runTenantDestructionSweep };

package/dist/tenant-lifecycle/testing.js

@@ -0,0 +1,42 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { append, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { tenantTable } from "../tenant/index.js";
+import { TENANT_AGGREGATE_TYPE, TENANT_DESTRUCTION_STARTED_EVENT_QN } from "./constants.js";
+import { runTenantDestructionSweep } from "./run-tenant-destroy.js";
+// Sidesteps the `request-destruction` write handler (needs user/auth/sessions
+// features wired) by seeding the same "destroying" state it would produce.
+export async function seedDestroyingTenant(db, tenantId) {
+    const now = getTemporal().Now.instant();
+    await updateRows(db, tenantTable, { status: "destroying", destroyStartedAt: now }, { id: tenantId });
+    await append(db, {
+        aggregateId: tenantId,
+        aggregateType: TENANT_AGGREGATE_TYPE,
+        tenantId,
+        expectedVersion: (await loadAggregate(db, tenantId, tenantId)).at(-1)?.version ?? 0,
+        type: TENANT_DESTRUCTION_STARTED_EVENT_QN,
+        payload: { startedAt: now.toString() },
+        metadata: { userId: "system", requestId: "test:destruction-started" },
+    });
+}
+export async function driveDestructionToCompletion(stack, db, tenantId, searchAdapter) {
+    const farFuture = getTemporal()
+        .Now.instant()
+        .add({ hours: 24 * 3650 });
+    let status = "";
+    for (let i = 0; i < 20; i++) {
+        await runTenantDestructionSweep({
+            db: stack.db,
+            registry: stack.registry,
+            now: farFuture,
+            searchAdapter,
+        });
+        const rows = await selectMany(db, tenantTable, { id: tenantId });
+        status = String(rows[0]?.["status"]);
+        if (status === "destroyed" || status === "destroyFailed")
+            break;
+    }
+    return status;
+}
+export { runTenantDestructionSweep };

package/dist/tier-engine/handlers/set-tenant-tier.write.js

@@ -45,6 +45,7 @@ export function createSetTenantTierWrite(opts = {}) {
                 .refine((t) => !opts.validTiers || opts.validTiers.has(t), { message: "unknown tier" }),
         }),
         access: { roles: ["SystemAdmin"] },
+        agent: { risk: "high" },
         escapeHatch: {
             grants: ["unsafeRaw"],
             reason: SET_TENANT_TIER_REASON,