@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -71,6 +71,11 @@ export type UnsubscribeRouteOptions = {
 };
 
 const UNSUBSCRIBE_EXPIRY = "7d";
+const RESUBSCRIBE_EXPIRY = "1h";
+const UNSUBSCRIBE_ISSUER = "kumiko:unsubscribe";
+const RESUBSCRIBE_AUDIENCE = "kumiko:resubscribe";
+
+type TokenPurpose = "unsubscribe" | "resubscribe";
 const MIN_UNSUBSCRIBE_SECRET_LENGTH = 32;
 
 function assertUnsubscribeSecret(secret: string, caller: string): void {
@@ -98,7 +103,7 @@ export async function signUnsubscribeToken(
   })
     .setProtectedHeader({ alg: "HS256" })
     .setSubject(String(payload.userId))
-    .setIssuer("kumiko:unsubscribe")
+    .setIssuer(UNSUBSCRIBE_ISSUER)
     .setIssuedAt()
     .setExpirationTime(UNSUBSCRIBE_EXPIRY)
     .sign(encodedSecret);
@@ -133,12 +138,10 @@ export async function signAddressUnsubscribeToken(
     })
       .setProtectedHeader({ alg: "HS256" })
       .setSubject(addressHash)
-      .setIssuer("kumiko:unsubscribe")
+      .setIssuer(UNSUBSCRIBE_ISSUER)
       .setIssuedAt()
-      // No expiry, unlike the user token above: this same token also signs
-      // the resubscribe (undo) direction, and an unsubscribe link mailed out
-      // today must keep working indefinitely — there's no signed-in flow for
-      // a no-account address to request a fresh link from.
+      // Only opt-out, so no expiry: a link mailed out today must keep working,
+      // there's no signed-in flow for a no-account address to request a fresh one.
       .sign(encodedSecret)
   );
 }
@@ -168,6 +171,35 @@ const CONFIRMATION_PAGE_HEADERS = {
   "Referrer-Policy": "no-referrer",
 } as const;
 
+// Undo token, handed out only in the response of a successful unsubscribe. A
+// separate audience and a short expiry keep the long-lived mailed unsubscribe
+// link from being able to undo an opt-out (and vice versa).
+async function signResubscribeToken(
+  verified: VerifiedUnsubscribe,
+  encodedSecret: Uint8Array,
+): Promise<string> {
+  const claims = {
+    tenantId: verified.tenantId,
+    notificationType: verified.notificationType,
+    channel: verified.channel,
+  };
+  const jwt =
+    verified.kind === "address"
+      ? new jose.SignJWT({
+          ...claims,
+          addressHash: verified.addressHash,
+          kind: "address",
+        }).setSubject(verified.addressHash)
+      : new jose.SignJWT(claims).setSubject(verified.userId);
+  return jwt
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuer(UNSUBSCRIBE_ISSUER)
+    .setAudience(RESUBSCRIBE_AUDIENCE)
+    .setIssuedAt()
+    .setExpirationTime(RESUBSCRIBE_EXPIRY)
+    .sign(encodedSecret);
+}
+
 // Every throw here must become the same ExtraRouteRejection(400,
 // unsubscribe_token_invalid) — anything else falls through to the
 // framework's generic 401 extra_route_signature_invalid mapping, which
@@ -175,6 +207,7 @@ const CONFIRMATION_PAGE_HEADERS = {
 async function verifyUnsubscribeToken(
   token: string | undefined,
   encodedSecret: Uint8Array,
+  purpose: TokenPurpose,
 ): Promise<VerifiedUnsubscribe> {
   try {
     if (!token) {
@@ -185,9 +218,22 @@ async function verifyUnsubscribeToken(
       );
     }
 
-    const { payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
-      issuer: "kumiko:unsubscribe",
-    });
+    const { payload: verifiedPayload } =
+      purpose === "resubscribe"
+        ? await jose.jwtVerify(token, encodedSecret, {
+            issuer: UNSUBSCRIBE_ISSUER,
+            audience: RESUBSCRIBE_AUDIENCE,
+            requiredClaims: ["exp"],
+          })
+        : await jose.jwtVerify(token, encodedSecret, { issuer: UNSUBSCRIBE_ISSUER });
+    // jose only checks `aud` when asked to, so an unsubscribe route would accept an undo token.
+    if (purpose === "unsubscribe" && verifiedPayload.aud !== undefined) {
+      throw new ExtraRouteRejection(
+        400,
+        UNSUBSCRIBE_TOKEN_INVALID_BODY,
+        "resubscribe token used as unsubscribe token",
+      );
+    }
 
     const addressAttempt = addressUnsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
     if (addressAttempt.success) {
@@ -329,6 +375,24 @@ function confirmationPage(token: string): string {
 </html>`;
 }
 
+function unsubscribedPage(resubscribeToken: string): string {
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex">
+<title>Unsubscribed</title>
+</head>
+<body>
+<p>You have been unsubscribed.</p>
+<form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
+<button type="submit">Undo</button>
+</form>
+</body>
+</html>`;
+}
+
 // One-click clients put the token in the query string; only the
 // confirmation-page form submits it in the body.
 function tokenFromPostRequest(request: SignatureExtraRouteVerifyRequest): string | undefined {
@@ -377,7 +441,7 @@ export function createUnsubscribeRoutes(
           "missing unsubscribe token",
         );
       }
-      await verifyUnsubscribeToken(token, encodedSecret);
+      await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
       return { token };
     },
     handler: async (c, { token }) =>
@@ -388,7 +452,8 @@ export function createUnsubscribeRoutes(
     method: "POST",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
-    verify: async (request) => verifyUnsubscribeToken(tokenFromPostRequest(request), encodedSecret),
+    verify: async (request) =>
+      verifyUnsubscribeToken(tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
     handler: async (c, verified, deps) => {
       // Token-verify passed — everything below is a legitimate write. Don't
       // swallow write-errors as "invalid token", that would mask real bugs
@@ -397,7 +462,9 @@ export function createUnsubscribeRoutes(
       if (!succeeded) {
         return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
       }
-      return c.html("You have been unsubscribed.", 200, { "Cache-Control": "no-store" });
+      return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
+        "Cache-Control": "no-store",
+      });
     },
   });
 
@@ -408,7 +475,8 @@ export function createUnsubscribeRoutes(
     method: "POST",
     path: DELIVERY_RESUBSCRIBE_PATH,
     entry: "signature",
-    verify: async (request) => verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret),
+    verify: async (request) =>
+      verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
     handler: async (c, verified, deps) => {
       const outcome = await dispatchResubscribeWrite(verified, deps);
       if (outcome === "limit_reached") {

package/packages/bundled-features/src/feature-toggles/feature.ts

@@ -108,9 +108,8 @@ export function createFeatureTogglesFeature(
     // process's handler calls runtime.broadcastToggle, which publishes on
     // GlobalFeatureToggleRuntime's syncSignal so every process (including
     // the one that won the cursor) applies the flip to its own snapshot —
-    // see toggle-runtime.ts and toggle-sync-signal.ts. Without a syncSignal
-    // configured (no REDIS_URL — single-process dev/test), broadcastToggle
-    // applies directly; there is nobody else to reach. Named "cache-sync"
+    // see toggle-runtime.ts and toggle-sync-signal.ts. The signal defaults to
+    // the cache-sync bus (Redis with REDIS_URL, process-local without). Named "cache-sync"
     // (not "projection" or "audit") because it's side-effect-only
     // infrastructure.
     //

package/packages/bundled-features/src/feature-toggles/toggle-runtime.ts

@@ -5,7 +5,15 @@ import {
   type Registry,
   type ToggleReader,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import {
+  type ClosableCacheSyncBus,
+  createDefaultCacheSyncBus,
+} from "@cosmicdrift/kumiko-framework/redis";
 import { globalFeatureStateTable } from "./global-feature-state-table.js";
+import { createCacheSyncToggleSignal } from "./toggle-sync-signal.js";
+
+const log = createFallbackLogger("kumiko:feature-toggles");
 
 // Cross-replica transport for a toggle flip (fw#2625). Deliberately narrow
 // (featureName + enabled, not a generic channel/payload pair) so a caller
@@ -15,6 +23,8 @@ import { globalFeatureStateTable } from "./global-feature-state-table.js";
 export type ToggleSyncSignal = {
   publish(featureName: string, enabled: boolean): void;
   onMessage(listener: (featureName: string, enabled: boolean) => void): void;
+  // Fires after the transport lost and restored its subscription: flips sent meanwhile are gone.
+  onResync?(listener: () => void): void;
 };
 
 // Holds the current global-override snapshot in memory and exposes a
@@ -38,6 +48,7 @@ export class GlobalFeatureToggleRuntime {
     private readonly db: DbConnection,
     private readonly registry: Registry,
     private readonly syncSignal?: ToggleSyncSignal,
+    private readonly ownedBus?: ClosableCacheSyncBus,
   ) {
     // Every process, including the one that calls broadcastToggle, learns
     // of a flip through this same subscription — mirrors the SSE broker's
@@ -46,6 +57,16 @@ export class GlobalFeatureToggleRuntime {
     this.syncSignal?.onMessage((featureName, enabled) => {
       this.apply(featureName, enabled);
     });
+    this.syncSignal?.onResync?.(() => {
+      this.refresh().catch((err: unknown) => {
+        log.error("snapshot reload after sync reconnect failed", { err });
+      });
+    });
+  }
+
+  // Only the runtime built by createFeatureToggleRuntime without an explicit signal owns one.
+  async close(): Promise<void> {
+    await this.ownedBus?.close();
   }
 
   async initialize(): Promise<void> {
@@ -121,15 +142,23 @@ export class GlobalFeatureToggleRuntime {
   };
 }
 
-// Factory for app-boot wiring: instantiate, initialize, return both the
-// runtime (for the set-handler to refresh) and the callback (for
-// createDispatcher's effectiveFeatures option).
+// Factory for app-boot wiring: instantiate, initialize, return the runtime (for the
+// set-handler to refresh; its effectiveFeatures feeds createDispatcher). Without an explicit
+// syncSignal the runtime builds one on the framework cache-sync bus: Redis-backed when
+// REDIS_URL is set, process-local otherwise. close() releases a bus it created.
 export async function createFeatureToggleRuntime(
   db: DbConnection,
   registry: Registry,
   syncSignal?: ToggleSyncSignal,
 ): Promise<GlobalFeatureToggleRuntime> {
-  const runtime = new GlobalFeatureToggleRuntime(db, registry, syncSignal);
-  await runtime.initialize();
+  const ownedBus = syncSignal ? undefined : createDefaultCacheSyncBus();
+  const signal = syncSignal ?? (ownedBus ? createCacheSyncToggleSignal(ownedBus) : undefined);
+  const runtime = new GlobalFeatureToggleRuntime(db, registry, signal, ownedBus);
+  try {
+    await runtime.initialize();
+  } catch (err) {
+    await runtime.close();
+    throw err;
+  }
   return runtime;
 }

package/packages/bundled-features/src/feature-toggles/toggle-sync-signal.ts

@@ -1,12 +1,15 @@
 import {
+  CACHE_SYNC_TOPICS,
+  type CacheSyncBus,
   createRedisPubSubSignal,
   type RedisClientOptions,
+  redisChannelPrefixFromEnv,
 } from "@cosmicdrift/kumiko-framework/redis";
 import type { ToggleSyncSignal } from "./toggle-runtime.js";
 
 // Single fixed channel — unlike the SSE broker there's no per-tenant/
 // per-user variance to multiplex, every toggle flip is global.
-const TOGGLE_SYNC_CHANNEL = "kumiko:feature-toggles:cache-sync";
+const TOGGLE_SYNC_CHANNEL_NAME = "kumiko:feature-toggles:cache-sync";
 
 export type RedisToggleSyncSignal = ToggleSyncSignal & {
   // Not on ToggleSyncSignal — the in-memory/no-signal path (GlobalFeature
@@ -27,31 +30,31 @@ function isTogglePayload(value: unknown): value is { featureName: string; enable
 // fw#2625: gives toggle-cache-sync the cross-replica transport its shared
 // dispatcher cursor needs — without this, only the one process that won
 // the shared cursor's toggle-set event would ever learn about a flip.
-// Same REDIS_URL-gated assumption as the SSE broker: a deployment with
-// replicas > 1 is expected to set REDIS_URL, so app-boot code should build
-// this only when REDIS_URL is present and pass it into
-// createFeatureToggleRuntime.
+// Standalone Redis transport for callers that want their own connections;
+// createFeatureToggleRuntime builds a cache-sync-bus signal by default.
 export function createRedisToggleSyncSignal(
   redisUrl: string,
   clientOptions?: RedisClientOptions,
+  channelPrefix: string = redisChannelPrefixFromEnv(),
 ): RedisToggleSyncSignal {
+  const toggleSyncChannel = `${channelPrefix}${TOGGLE_SYNC_CHANNEL_NAME}`;
   const signal = createRedisPubSubSignal({
     redisUrl,
-    channelPattern: TOGGLE_SYNC_CHANNEL,
+    channelPattern: toggleSyncChannel,
     label: "feature-toggles",
     ...(clientOptions ? { clientOptions } : {}),
   });
 
   return {
     publish(featureName, enabled) {
-      signal.publish(TOGGLE_SYNC_CHANNEL, { featureName, enabled });
+      signal.publish(toggleSyncChannel, { featureName, enabled });
     },
     onMessage(listener) {
       signal.onMessage((_channel, payload) => {
         if (!isTogglePayload(payload)) {
           // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.log in a raw PubSubSignal handler.
           console.error(
-            `[kumiko:feature-toggles] dropping malformed cache-sync message on "${TOGGLE_SYNC_CHANNEL}"`,
+            `[kumiko:feature-toggles] dropping malformed cache-sync message on "${toggleSyncChannel}"`,
           );
           // skip: malformed message already logged above, nothing to apply
           return;
@@ -62,3 +65,23 @@ export function createRedisToggleSyncSignal(
     close: signal.close,
   };
 }
+
+// Reuses the framework cache-sync bus (local without REDIS_URL, Redis-backed with it) so
+// toggles need no Pub/Sub wiring of their own. The bus applies a publish locally first.
+export function createCacheSyncToggleSignal(bus: CacheSyncBus): ToggleSyncSignal {
+  return {
+    publish(featureName, enabled) {
+      bus.publish(CACHE_SYNC_TOPICS.featureToggle, { featureName, enabled });
+    },
+    onMessage(listener) {
+      bus.subscribe(CACHE_SYNC_TOPICS.featureToggle, (payload) => {
+        // skip: foreign or malformed payload on the topic
+        if (!isTogglePayload(payload)) return;
+        listener(payload.featureName, payload.enabled);
+      });
+    },
+    onResync(listener) {
+      bus.onResync(listener);
+    },
+  };
+}

package/packages/bundled-features/src/file-derivatives/handlers/public-variant.query.ts

@@ -42,7 +42,10 @@ type FileRefRow = {
 };
 
 // Declared variants are implicitly public once the entityType check passes — `fieldName`/`variant` allow per-variant opt-out.
+// entityType/entityId/fieldName of a FileRef are client-supplied at upload, so a predicate that
+// serves "the public image of X" must also match `fileRefId` against the row it trusts.
 export type DerivativePublicPredicateArgs = {
+  readonly fileRefId: string;
   readonly entityId: string;
   readonly tenantId: TenantId;
   readonly fieldName: string;
@@ -119,7 +122,13 @@ export const publicVariantQuery = defineQueryHandler({
     }
 
     const isPublic = await usage.options.isPublic(
-      { entityId, tenantId: ctx.user.tenantId, fieldName, variant: query.payload.variant },
+      {
+        fileRefId: query.payload.fileRefId,
+        entityId,
+        tenantId: ctx.user.tenantId,
+        fieldName,
+        variant: query.payload.variant,
+      },
       ctx,
     );
     if (!isPublic) return null;

package/packages/bundled-features/src/files/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "FileHandle.derive throws for suffixes outside <name>-<16 hex>",
+    "detail": "Final review batch D.\n- `FileHandle.derive(suffix)` now throws unless the suffix is `<name>-<16 hex>` (build it with `variantSuffix(name, spec)`). Free-form suffixes such as `derive(\"thumb\")` wrote keys the forget/tenant-destroy sweep could not recognize, so those binaries survived erasure. Callers passing a bare name must switch to `variantSuffix`.\n- `resolveKmsWiring` / `requireKmsWiring` throw when a `*_CIPHERTEXT` slot is set without its plaintext, pointing at the async entry points, instead of a misleading \"trio required\" error or a silent plaintext-PII fallback.\n- Event-PII owner/`whenAbsent` resolution now also runs without a configured KMS, so a missing owner fails in dev like in prod.\n- PII event backfill queues rebuilds under a per-run migration id, so a peer replica's re-queue is no longer cleared by another run.\n- `seedAdminGuarded` re-writes the canonical admin's email so the blind index is repaired, and skips undecryptable foreign user rows instead of aborting the boot seed.\n- A tenant-bound `FileContext.list` refuses prefixes outside the tenant's key space.\n- An entityList whose create screen was dropped for the caller's roles now carries `createUnavailable`, so the renderer no longer falls back to a generic create form.\n- Boot validation rejects an object-form `redirect` with `idFrom` whose same-feature target screen carries no id.\n- `defineFeature` throws when `dedupeOptions` holds a nested object (it can never compare equal across two mounts).\n- `FileContext.ref` and `list` (tenant-bound) refuse keys outside `${tenantId}/`; list columns accept `virtual: true`; `httpRoute` session-only routes now pass the global IP rate limit; tenant timezone cache TTL is 30 s; text fields without a personal stance warn at boot; the orphan-derivative sweep keeps derivatives whose original still exists; `piiFields` owner fields that can never yield a string throw unless `whenAbsent` is set.",
+    "migration": "Build the suffix with variantSuffix(name, spec) instead of passing a free-form string."
+  },
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "A tenant-bound FileContext.list throws for prefixes outside the tenant's key space",
+    "migration": "Pass a prefix that starts with `${tenantId}/`."
+  },
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "A tenant-bound FileContext.ref throws for keys outside the tenant's key space",
+    "migration": "Use keys that start with `${tenantId}/`."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "The signed download URL carries a neutral file name instead of the personal fileName"
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

package/packages/bundled-features/src/files-tenant-data/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "The orphan-derivative sweep keeps derivatives whose original still exists in storage"
+  },
   {
     "version": "0.275.0",
     "type": "breaking",

package/packages/bundled-features/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -140,6 +140,10 @@ export async function sweepOrphanedDerivativesJob(
       { limit: 1 },
     );
     if (owners.length > 0) return "skipped";
+    // Binaries written through ctx.files.ref(key) (and their derive()d
+    // variants) never get a fileRef row; an original still sitting in storage
+    // means the derivative is not an orphan.
+    if (await candidate.provider.exists(candidate.originalKey)) return "skipped";
     if (dryRun) {
       dryRunWouldDelete++;
       return "skipped";

package/packages/bundled-features/src/files-tenant-data/hooks.ts

@@ -55,6 +55,7 @@ import {
   type StorageProviderHookCtx,
   type TenantDataDestroyHook,
   type TenantDataHookCtx,
+  type TenantDestroyHookResult,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -64,6 +65,7 @@ import {
   storageKeyStemPrefix,
   tenantStoragePrefixes,
 } from "@cosmicdrift/kumiko-framework/files";
+import { type ChunkedMigrationResult, runChunkedMigration } from "../shared/index.js";
 
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 
@@ -72,6 +74,8 @@ const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName
 // or a single unbounded array for a tenant with a huge prefix.
 const SURVIVOR_CHECK_BATCH_SIZE = 500;
 
+const DESTROY_CHUNK_SIZE = 500;
+
 function chunk<T>(items: readonly T[], size: number): T[][] {
   const chunks: T[][] = [];
   for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
@@ -82,27 +86,54 @@ function isUnderOwnPrefix(storageKey: string, prefixes: readonly string[]): bool
   return prefixes.some((prefix) => storageKey.startsWith(prefix));
 }
 
+function toDestroyHookResult(
+  result: ChunkedMigrationResult,
+  failureMessage: () => string | undefined,
+): TenantDestroyHookResult {
+  // A failure on the last item ends the run as "done" (nothing left to batch),
+  // so the failed count, not the stop reason, decides fail-closed.
+  if (result.failed > 0) {
+    throw new Error(failureMessage() ?? "files-tenant-data: destroy chunk failed");
+  }
+  return { done: result.stoppedReason === "done", processed: result.migrated };
+}
+
 export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
-  const rows = await ctx.db.selectMany<{ id: string; storageKey: string }>(fileRefsTable, {
-    tenantId: ctx.tenantId,
-  });
   const ownPrefixes = tenantStoragePrefixes(ctx.tenantId);
   const user = createSystemUser(ctx.tenantId);
-  for (const row of rows) {
-    if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
-      await deleteHandedOverBinary(ctx, row.storageKey);
-    }
-    const result = await crud.forget({ id: row.id }, user, ctx.db);
-    // Executor writes return {isSuccess:false} instead of throwing — a
-    // discarded result would report this destroy stage "succeeded" while the
-    // row (and its PII fileName) survives. Throw so the pipeline's
-    // retry/abandon handling sees it.
-    if (!result.isSuccess) {
-      throw new Error(
-        `files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${result.error.message}`,
-      );
-    }
-  }
+  let firstFailure: string | undefined;
+  // Converges without a cursor: forget() hard-deletes, so each batch query
+  // returns the next rows.
+  const result = await runChunkedMigration<{ id: string; storageKey: string }>({
+    nextBatch: () =>
+      ctx.db.selectMany<{ id: string; storageKey: string }>(
+        fileRefsTable,
+        { tenantId: ctx.tenantId },
+        { limit: DESTROY_CHUNK_SIZE },
+      ),
+    migrateRow: async (row) => {
+      if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
+        await deleteHandedOverBinary(ctx, row.storageKey);
+      }
+      const forgotten = await crud.forget({ id: row.id }, user, ctx.db);
+      // Executor writes return {isSuccess:false} instead of throwing — a
+      // discarded result would report this destroy stage "succeeded" while the
+      // row (and its PII fileName) survives. Throw so the pipeline's
+      // retry/abandon handling sees it.
+      if (!forgotten.isSuccess) {
+        throw new Error(
+          `files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${forgotten.error.message}`,
+        );
+      }
+      return "migrated";
+    },
+    maxFailures: 1,
+    deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+    onRowError: (_row, err) => {
+      firstFailure = err instanceof Error ? err.message : String(err);
+    },
+  });
+  return toDestroyHookResult(result, () => firstFailure);
 };
 
 // The bytes live under the tenant that uploaded them (`<tenantId>/…` or
@@ -170,17 +201,36 @@ export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async
   }
   // Provider resolved — a list()/delete() failure from here IS fail-closed:
   // the "files" stage throws, tenant-lifecycle's retry/abandon handling sees
-  // it, and the next sweep tick retries (list+delete are idempotent, so this
-  // converges rather than double-deleting or erroring on a missing key).
+  // it and retries up to the stage's attempt cap before abandoning the destroy
+  // (list+delete are idempotent, so a retry converges rather than
+  // double-deleting or erroring on a missing key).
+  let processed = 0;
   for (const prefix of tenantStoragePrefixes(tenantId)) {
     const keys = await provider.list(prefix);
     const keptStemPrefixes = await survivorStemPrefixes(ctx.db, keys);
-    for (const key of keys) {
-      if (keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix))) continue;
-      assertSafeStorageKey(key);
-      await provider.delete(key);
-    }
+    const deletableKeys = keys.filter(
+      (key) => !keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix)),
+    );
+    const pending = [...deletableKeys];
+    let firstFailure: string | undefined;
+    const result = await runChunkedMigration<string>({
+      nextBatch: async () => pending.splice(0, DESTROY_CHUNK_SIZE),
+      migrateRow: async (key) => {
+        assertSafeStorageKey(key);
+        await provider.delete(key);
+        return "migrated";
+      },
+      maxFailures: 1,
+      deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+      onRowError: (_key, err) => {
+        firstFailure = err instanceof Error ? err.message : String(err);
+      },
+    });
+    const hookResult = toDestroyHookResult(result, () => firstFailure);
+    processed += result.migrated;
+    if (!hookResult.done) return { done: false, processed };
   }
+  return { done: true, processed };
 };
 
 // Any listed key that is itself a surviving row's exact storageKey means a

package/packages/bundled-features/src/folders/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "folder:delete removes assignments whose host entity is gone instead of refusing forever",
+    "detail": "An assignment pointing at a hard-deleted, soft-deleted or unregistered host blocked folder:delete permanently with folder_has_assignments, because clear-folder needs a visible host and could not remove it. folder:delete now removes such assignments through the event-store executor (normal delete events) before the check, without the caller's read gate. Assignments of live hosts, including ones the caller cannot see, still block with folder_has_assignments. A refused delete removes nothing. The cleanup runs lazily at folder:delete, not in a host-delete hook, so restoring a soft-deleted host before then keeps its folder."
+  },
   {
     "version": "0.246.0",
     "type": "improvement",

package/packages/bundled-features/src/folders/feature.ts

@@ -25,7 +25,7 @@ import {
   type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { hasWhereRule } from "../shared/index.js";
+import { assertNoWhereRuleInOwnershipWrite } from "../shared/index.js";
 import { DEFAULT_FOLDER_ACCESS, FOLDERS_FEATURE_NAME } from "./constants.js";
 import { createFolderAssignmentEntity, folderEntity } from "./entity.js";
 import { createClearFolderHandler } from "./handlers/clear-folder.write.js";
@@ -166,17 +166,7 @@ export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof f
   ) {
     return foldersFeature;
   }
-  if (hasWhereRule(opts.ownership?.write)) {
-    throw new Error(
-      "createFoldersFeature({ ownership }): ownership.write must not contain a " +
-        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
-        "layer (the read path, via buildOwnershipClause). Write paths that " +
-        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
-        "evaluate them, so such a rule can only ever deny — boot validation " +
-        "rejects it too (fw#2626). Use a `from()` rule for ownership.write, or " +
-        "leave it unset.",
-    );
-  }
+  assertNoWhereRuleInOwnershipWrite("createFoldersFeature", opts.ownership?.write);
   if (opts.parents !== undefined && opts.parents.length === 0) {
     throw new Error(
       "createFoldersFeature({ parents }): parents must not be an empty array — " +