@cosmicdrift/kumiko-bundled-features 0.352.0 → 0.354.0

package/dist/delivery/unsubscribe.js

@@ -32,6 +32,9 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
     addressHash: z.string().min(1),
 });
 const UNSUBSCRIBE_EXPIRY = "7d";
+const RESUBSCRIBE_EXPIRY = "1h";
+const UNSUBSCRIBE_ISSUER = "kumiko:unsubscribe";
+const RESUBSCRIBE_AUDIENCE = "kumiko:resubscribe";
 const MIN_UNSUBSCRIBE_SECRET_LENGTH = 32;
 function assertUnsubscribeSecret(secret, caller) {
     if (secret.length < MIN_UNSUBSCRIBE_SECRET_LENGTH) {
@@ -51,7 +54,7 @@ export async function signUnsubscribeToken(payload, secret) {
     })
         .setProtectedHeader({ alg: "HS256" })
         .setSubject(String(payload.userId))
-        .setIssuer("kumiko:unsubscribe")
+        .setIssuer(UNSUBSCRIBE_ISSUER)
         .setIssuedAt()
         .setExpirationTime(UNSUBSCRIBE_EXPIRY)
         .sign(encodedSecret);
@@ -79,12 +82,10 @@ export async function signAddressUnsubscribeToken(payload, secret) {
     })
         .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));
 }
 // RFC 8058 fixed value — both the List-Unsubscribe-Post header and the body a
@@ -94,18 +95,50 @@ const CONFIRMATION_PAGE_HEADERS = {
     "Cache-Control": "no-store",
     "Referrer-Policy": "no-referrer",
 };
+// 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, encodedSecret) {
+    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
 // would leak jose's internal error text into the response body.
-async function verifyUnsubscribeToken(token, encodedSecret) {
+async function verifyUnsubscribeToken(token, encodedSecret, purpose) {
     try {
         if (!token) {
             throw new ExtraRouteRejection(400, UNSUBSCRIBE_TOKEN_INVALID_BODY, "missing unsubscribe token");
         }
-        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) {
             const parsed = addressAttempt.data;
@@ -211,6 +244,23 @@ function confirmationPage(token) {
 </body>
 </html>`;
 }
+function unsubscribedPage(resubscribeToken) {
+    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) {
@@ -251,7 +301,7 @@ export function createUnsubscribeRoutes(options) {
             if (!token) {
                 throw new ExtraRouteRejection(400, UNSUBSCRIBE_TOKEN_INVALID_BODY, "missing unsubscribe token");
             }
-            await verifyUnsubscribeToken(token, encodedSecret);
+            await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
             return { token };
         },
         handler: async (c, { token }) => c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
@@ -260,7 +310,7 @@ export function createUnsubscribeRoutes(options) {
         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
@@ -269,7 +319,9 @@ export function createUnsubscribeRoutes(options) {
             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",
+            });
         },
     });
     // Undo direction: token only from the JSON/form body, never the query
@@ -279,7 +331,7 @@ export function createUnsubscribeRoutes(options) {
         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/dist/document-ingest-foundation/entity.d.ts

@@ -14,6 +14,7 @@ export declare const documentExtractEntity: import("@cosmicdrift/kumiko-types/fi
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -35,6 +36,7 @@ export declare const documentExtractEntity: import("@cosmicdrift/kumiko-types/fi
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -75,6 +77,7 @@ export declare const documentExtractsTable: import("@cosmicdrift/kumiko-framewor
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -96,6 +99,7 @@ export declare const documentExtractsTable: import("@cosmicdrift/kumiko-framewor
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/feature-toggles/feature.js

@@ -64,9 +64,8 @@ export function createFeatureTogglesFeature(options = {}) {
         // 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/dist/feature-toggles/toggle-runtime.d.ts

@@ -1,16 +1,20 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type ClosableCacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
 export type ToggleSyncSignal = {
     publish(featureName: string, enabled: boolean): void;
     onMessage(listener: (featureName: string, enabled: boolean) => void): void;
+    onResync?(listener: () => void): void;
 };
 export declare class GlobalFeatureToggleRuntime {
     private readonly db;
     private readonly registry;
     private readonly syncSignal?;
+    private readonly ownedBus?;
     private snapshot;
     private appliedDuringLoad;
-    constructor(db: DbConnection, registry: Registry, syncSignal?: ToggleSyncSignal | undefined);
+    constructor(db: DbConnection, registry: Registry, syncSignal?: ToggleSyncSignal | undefined, ownedBus?: ClosableCacheSyncBus | undefined);
+    close(): Promise<void>;
     initialize(): Promise<void>;
     refresh(): Promise<void>;
     apply(featureName: string, enabled: boolean): void;

package/dist/feature-toggles/toggle-runtime.js

@@ -1,6 +1,10 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { computeEffectiveFeatures, } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { 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");
 // Holds the current global-override snapshot in memory and exposes a
 // synchronous reader — the dispatcher's feature-gate calls it on every
 // handler invocation, so this must not do I/O on the hot path. The
@@ -16,14 +20,16 @@ export class GlobalFeatureToggleRuntime {
     db;
     registry;
     syncSignal;
+    ownedBus;
     snapshot = new Map();
     // Flips applied while a snapshot load is in flight. The load's SELECT may have
     // started before the flip committed, so its rows can be older than these.
     appliedDuringLoad;
-    constructor(db, registry, syncSignal) {
+    constructor(db, registry, syncSignal, ownedBus) {
         this.db = db;
         this.registry = registry;
         this.syncSignal = syncSignal;
+        this.ownedBus = ownedBus;
         // Every process, including the one that calls broadcastToggle, learns
         // of a flip through this same subscription — mirrors the SSE broker's
         // publish-then-echo-to-self pattern instead of a separate local-apply
@@ -31,6 +37,15 @@ export class GlobalFeatureToggleRuntime {
         this.syncSignal?.onMessage((featureName, enabled) => {
             this.apply(featureName, enabled);
         });
+        this.syncSignal?.onResync?.(() => {
+            this.refresh().catch((err) => {
+                log.error("snapshot reload after sync reconnect failed", { err });
+            });
+        });
+    }
+    // Only the runtime built by createFeatureToggleRuntime without an explicit signal owns one.
+    async close() {
+        await this.ownedBus?.close();
     }
     async initialize() {
         const pendingFlips = new Map();
@@ -99,11 +114,20 @@ export class GlobalFeatureToggleRuntime {
         return computeEffectiveFeatures(this.registry, reader);
     };
 }
-// 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, registry, syncSignal) {
-    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/dist/feature-toggles/toggle-sync-signal.d.ts

@@ -1,6 +1,7 @@
-import { type RedisClientOptions } from "@cosmicdrift/kumiko-framework/redis";
+import { type CacheSyncBus, type RedisClientOptions } from "@cosmicdrift/kumiko-framework/redis";
 import type { ToggleSyncSignal } from "./toggle-runtime.js";
 export type RedisToggleSyncSignal = ToggleSyncSignal & {
     close(): Promise<void>;
 };
-export declare function createRedisToggleSyncSignal(redisUrl: string, clientOptions?: RedisClientOptions): RedisToggleSyncSignal;
+export declare function createRedisToggleSyncSignal(redisUrl: string, clientOptions?: RedisClientOptions, channelPrefix?: string): RedisToggleSyncSignal;
+export declare function createCacheSyncToggleSignal(bus: CacheSyncBus): ToggleSyncSignal;

package/dist/feature-toggles/toggle-sync-signal.js

@@ -1,7 +1,7 @@
-import { createRedisPubSubSignal, } from "@cosmicdrift/kumiko-framework/redis";
+import { CACHE_SYNC_TOPICS, createRedisPubSubSignal, redisChannelPrefixFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
 // 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";
 function isTogglePayload(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -11,26 +11,25 @@ function isTogglePayload(value) {
 // 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.
-export function createRedisToggleSyncSignal(redisUrl, clientOptions) {
+// Standalone Redis transport for callers that want their own connections;
+// createFeatureToggleRuntime builds a cache-sync-bus signal by default.
+export function createRedisToggleSyncSignal(redisUrl, clientOptions, channelPrefix = redisChannelPrefixFromEnv()) {
+    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}"`);
+                    console.error(`[kumiko:feature-toggles] dropping malformed cache-sync message on "${toggleSyncChannel}"`);
                     // skip: malformed message already logged above, nothing to apply
                     return;
                 }
@@ -40,3 +39,23 @@ export function createRedisToggleSyncSignal(redisUrl, clientOptions) {
         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) {
+    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/dist/file-derivatives/handlers/public-variant.query.d.ts

@@ -1,6 +1,7 @@
 import { EXT_DERIVATIVE_PUBLIC_PREDICATE, type HandlerContext, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 export type DerivativePublicPredicateArgs = {
+    readonly fileRefId: string;
     readonly entityId: string;
     readonly tenantId: TenantId;
     readonly fieldName: string;

package/dist/file-derivatives/handlers/public-variant.query.js

@@ -78,7 +78,13 @@ export const publicVariantQuery = defineQueryHandler({
         if (!isDerivativePublicPredicatePlugin(usage.options)) {
             throw new Error(`file-derivatives: "${usage.entityName}" registered ${EXT_DERIVATIVE_PUBLIC_PREDICATE} without an isPublic(args, ctx) — extension options must be a DerivativePublicPredicatePlugin.`);
         }
-        const isPublic = await usage.options.isPublic({ entityId, tenantId: ctx.user.tenantId, fieldName, variant: query.payload.variant }, ctx);
+        const isPublic = await usage.options.isPublic({
+            fileRefId: query.payload.fileRefId,
+            entityId,
+            tenantId: ctx.user.tenantId,
+            fieldName,
+            variant: query.payload.variant,
+        }, ctx);
         if (!isPublic)
             return null;
         // ctx.files/ctx.derivatives are optional on HandlerContext (only wired

package/dist/files-tenant-data/handlers/sweep-orphaned-derivatives.job.js

@@ -99,6 +99,11 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
         const owners = await selectMany(db, fileRefsTable, { tenantId: candidate.tenantId, storageKey: candidate.originalKey }, { 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/dist/files-tenant-data/hooks.js

@@ -49,11 +49,13 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, parseTenantId, } from "@cosmicdrift/kumiko-framework/engine";
 import { assertSafeStorageKey, fileRefEntity, fileRefsTable, storageKeyStemPrefix, tenantStoragePrefixes, } from "@cosmicdrift/kumiko-framework/files";
+import { runChunkedMigration } from "../shared/index.js";
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 // Existence-check batch size for fileRefStorageDestroyHook's survivor lookup
 // — bounds each query instead of one `storage_key = ANY(...)` per listed key,
 // 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(items, size) {
     const chunks = [];
     for (let i = 0; i < items.length; i += size)
@@ -63,25 +65,43 @@ function chunk(items, size) {
 function isUnderOwnPrefix(storageKey, prefixes) {
     return prefixes.some((prefix) => storageKey.startsWith(prefix));
 }
+function toDestroyHookResult(result, failureMessage) {
+    // 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 = async (ctx) => {
-    const rows = await ctx.db.selectMany(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;
+    // Converges without a cursor: forget() hard-deletes, so each batch query
+    // returns the next rows.
+    const result = await runChunkedMigration({
+        nextBatch: () => ctx.db.selectMany(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
 // `exports/<tenantId>/…`), so with per-tenant storage config that tenant's
@@ -137,18 +157,35 @@ export const fileRefStorageDestroyHook = async (tenantId, ctx) => {
     }
     // 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;
+        const result = await runChunkedMigration({
+            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
 // foreign tenant still owns it (see header comment) — its stem prefix then

package/dist/folders/entity.d.ts

@@ -4,6 +4,7 @@ export declare const folderEntity: EntityDefinition<{
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -25,6 +26,7 @@ export declare const folderEntity: EntityDefinition<{
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -48,6 +50,7 @@ export declare function createFolderAssignmentEntity(access?: EntityDefinition["
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -69,6 +72,7 @@ export declare function createFolderAssignmentEntity(access?: EntityDefinition["
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -90,6 +94,7 @@ export declare function createFolderAssignmentEntity(access?: EntityDefinition["
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -113,6 +118,7 @@ export declare const folderAssignmentEntity: EntityDefinition<{
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -134,6 +140,7 @@ export declare const folderAssignmentEntity: EntityDefinition<{
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -155,6 +162,7 @@ export declare const folderAssignmentEntity: EntityDefinition<{
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/folders/feature.js

@@ -15,7 +15,7 @@
 // Deferred: reparenting with cycle-check (folder:update CAN change parentId, but
 // no UI exposes it in v1 — folders-view guards cycles defensively).
 import { defineEntityCreateHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, } 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";
@@ -80,15 +80,7 @@ export function createFoldersFeature(opts = {}) {
         opts.parents === undefined) {
         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 — " +
             "an empty allowlist rejects every set-folder call and hides every " +