@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

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

@@ -16,6 +16,12 @@ import type {
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import * as z from "zod";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import {
+  emailAttachmentRefSchema,
+  MAX_EMAIL_ATTACHMENTS,
+  toAttachmentRef,
+} from "./attachment-ref.js";
 import { appendAttemptEvent } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank } from "./constants.js";
@@ -49,7 +55,14 @@ const renderJobPayloadSchema = z.object({
 
 const sendJobPayloadSchema = renderJobPayloadSchema.extend({
   rendered: z
-    .object({ html: z.string(), subject: z.string(), text: z.string().optional() })
+    .object({
+      html: z.string(),
+      subject: z.string(),
+      text: z.string().optional(),
+      fromName: z.string().optional(),
+      replyTo: z.string().optional(),
+      attachments: z.array(emailAttachmentRefSchema).max(MAX_EMAIL_ATTACHMENTS).optional(),
+    })
     .optional(),
 });
 
@@ -63,18 +76,36 @@ function requireTenantScopedDeps(
   if (!registry) throw new Error("delivery job: missing registry in job context");
   // delivery is r.systemScope()'d, so JobContext.systemDb is guaranteed; unsafeRaw
   // hands the underlying DbConnection to both — safe since they filter by tenantId themselves.
+  // Attachment lookups read only this tenant's FileRefs, plus the system tenant's for inline images.
   if (!ctx.systemDb) {
     throw new InternalError({
       message: "delivery job: ctx.systemDb missing on a system-scoped job",
     });
   }
+  // Also makes ctx.config (built for the job's tenant) the accessor of the payload tenant;
+  // job contexts carry no configFor.
   ctx.systemDb.assertTenantMatch(tenantId);
   const db = ctx.systemDb.unsafeRaw(
-    "delivery attempt append and channel context filter by this job's tenantId themselves",
+    "attempt append and channel context filter by this job's tenantId; attachment lookup reads only the job tenant's FileRefs plus, for inline images, the system tenant's",
   ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
   return { db, registry };
 }
 
+function toSendRendered(
+  rendered: RenderedMessage,
+): z.infer<typeof sendJobPayloadSchema>["rendered"] {
+  return {
+    html: rendered.html,
+    subject: rendered.subject,
+    ...(rendered.text !== undefined && { text: rendered.text }),
+    ...(rendered.fromName !== undefined && { fromName: rendered.fromName }),
+    ...(rendered.replyTo !== undefined && { replyTo: rendered.replyTo }),
+    ...(rendered.attachments !== undefined && {
+      attachments: rendered.attachments.map(toAttachmentRef),
+    }),
+  };
+}
+
 function resolveChannel(registry: Registry, name: string): DeliveryChannel {
   const channel = collectChannels(registry).find((c) => c.name === name);
   if (!channel) throw new Error(`delivery job: unknown channel "${name}"`);
@@ -111,15 +142,11 @@ function entryFor(
   };
 }
 
-// Only the final retry frees the key: earlier failures are retried by the runner and
-// must still dedup. Assumes ctx.redis is the handle the service claimed on; runProdApp
-// wires the same instance into both.
-async function releaseIdempotencyOnTerminalFailure(
-  ctx: JobContext,
-  p: RenderJobPayload,
-): Promise<void> {
-  // skip: nothing to release before the last attempt or without an idempotency key
-  if (!ctx.finalAttempt || !p.idempotencyKey) return;
+// Assumes ctx.redis is the handle the service claimed on; runProdApp wires the same
+// instance into both.
+async function releaseIdempotencyKey(ctx: JobContext, p: RenderJobPayload): Promise<void> {
+  // skip: no idempotency key was claimed for this notification
+  if (!p.idempotencyKey) return;
   if (!ctx.redis) {
     ctx.log.warn("delivery: idempotency key not released, job context has no redis", {
       notificationType: p.notificationType,
@@ -135,6 +162,33 @@ async function releaseIdempotencyOnTerminalFailure(
   }
 }
 
+// Only the final retry frees the key: earlier failures are retried by the runner and
+// must still dedup.
+async function releaseIdempotencyOnTerminalFailure(
+  ctx: JobContext,
+  p: RenderJobPayload,
+): Promise<void> {
+  // skip: not the last attempt, the runner retries and the key must keep deduplicating
+  if (!ctx.finalAttempt) return;
+  await releaseIdempotencyKey(ctx, p);
+}
+
+// Covers every throw after the payload parsed, not just the attempt-logged ones: a
+// missing registry or unknown channel on the last attempt would otherwise hold the key
+// until its TTL.
+async function releasingKeyOnTerminalFailure<T>(
+  ctx: JobContext,
+  p: RenderJobPayload,
+  run: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await run();
+  } catch (err) {
+    await releaseIdempotencyOnTerminalFailure(ctx, p);
+    throw err;
+  }
+}
+
 // The job runner stores err.message in the run row, and BullMQ keeps failedReason and
 // the stack trace in Redis in plain text, so the rethrown error carries only the code.
 // The redacted message goes to the log.
@@ -157,7 +211,6 @@ async function failAttempt(
     p.deliveryAttemptId,
     entryFor(p, "failed", code, p.address),
   );
-  await releaseIdempotencyOnTerminalFailure(ctx, p);
   throw new Error(code);
 }
 
@@ -166,10 +219,22 @@ async function failAttempt(
 // the send step is never reached, so a stuck render can't half-send.
 export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
   const p = renderJobPayloadSchema.parse(payload);
+  return releasingKeyOnTerminalFailure(ctx, p, () => renderStep(p, ctx));
+};
+
+async function renderStep(p: RenderJobPayload, ctx: JobContext): Promise<void> {
   const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
   const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
   const channel = resolveChannel(registry, p.channelName);
-  const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
+  const channelCtx = buildChannelContext(
+    db,
+    registry,
+    undefined,
+    tenantId,
+    ctx.secrets,
+    ctx.config,
+    (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
+  );
 
   let rendered: RenderedMessage;
   try {
@@ -184,23 +249,35 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
     const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key — dispatch lives on the concrete runner
     await jobRunner.dispatch(
       DeliveryJobs.send,
-      { ...p, rendered },
+      { ...p, rendered: toSendRendered(rendered) },
       { priority: deliveryPriorityRank[p.priority] },
     );
   } catch (err) {
     return failAttempt(ctx, db, registry, p, "channel_error", err);
   }
-};
+}
 
 // Deliver via the channel using the rendered payload (if any). On failure:
 // record the terminal failed event and rethrow so BullMQ retries the send with
 // the same already-rendered HTML — no re-render needed.
 export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
   const p = sendJobPayloadSchema.parse(payload);
+  return releasingKeyOnTerminalFailure(ctx, p, () => sendStep(p, ctx));
+};
+
+async function sendStep(p: z.infer<typeof sendJobPayloadSchema>, ctx: JobContext): Promise<void> {
   const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
   const { db, registry } = requireTenantScopedDeps(ctx, tenantId);
   const channel = resolveChannel(registry, p.channelName);
-  const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
+  const channelCtx = buildChannelContext(
+    db,
+    registry,
+    undefined,
+    tenantId,
+    ctx.secrets,
+    ctx.config,
+    (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
+  );
 
   try {
     const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);
@@ -216,7 +293,10 @@ export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
         result.confirmed,
       ),
     );
+    // A soft failure ends the job successfully, so no retry follows and the caller's
+    // retry must not be skipped as a duplicate.
+    if (result.status === "failed") await releaseIdempotencyKey(ctx, p);
   } catch (err) {
     return failAttempt(ctx, db, registry, p, "send_failed", err);
   }
-};
+}

package/packages/bundled-features/src/delivery/notify-factory.ts

@@ -1,4 +1,4 @@
-import type { NotifyFactory } from "@cosmicdrift/kumiko-framework/engine";
+import type { NotifyFactory, NotifyFn, NotifyOptions } from "@cosmicdrift/kumiko-framework/engine";
 import type { DeliveryService } from "./types.js";
 
 // The same binding runProdApp wires into the app context: the calling context's
@@ -8,12 +8,17 @@ export function createDeliveryNotifyFactory(
   deliveryService: Pick<DeliveryService, "notify">,
   options: { readonly deliverQueuedInline?: boolean } = {},
 ): NotifyFactory {
-  return (user, tenantId, jobDispatcher) => (notificationType, notifyOptions) =>
-    deliveryService.notify(
-      notificationType,
-      notifyOptions,
-      user,
-      tenantId,
-      options.deliverQueuedInline === true ? undefined : jobDispatcher,
-    );
+  return (user, tenantId, jobDispatcher, deliveryDb, fileProviderResolver) => {
+    const notify: NotifyFn = (notificationType: string, notifyOptions: NotifyOptions) =>
+      deliveryService.notify(
+        notificationType,
+        notifyOptions,
+        user,
+        tenantId,
+        options.deliverQueuedInline === true ? undefined : jobDispatcher,
+        deliveryDb,
+        fileProviderResolver,
+      );
+    return notify;
+  };
 }

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

@@ -1,6 +1,12 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { EscapeHatchAuditSink, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  ConfigAccessor,
+  EscapeHatchAuditSink,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
@@ -19,6 +25,8 @@ export type CreateDeliveryTestContextOptions = {
   readonly jobRunner?: JobRunner;
   readonly secrets?: SecretsContext;
   readonly idempotencyRedis?: Redis;
+  readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
+  readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
 };
 
 /**

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

@@ -1,21 +1,36 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
   DeliveryErrorCode,
   NotifyDeliveryStatus,
+  NotifyDispatched,
   NotifyJobDispatcher,
   NotifyOptions,
   NotifyPriority,
-  NotifyResult,
   Registry,
   SessionUser,
   TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { MailPayload, RenderedTemplateRef } from "../renderer-foundation/index.js";
+import type { EmailAttachmentRef } from "./attachment-ref.js";
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 
 // --- Channel Interface ---
 
+export type RenderedMail = {
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+  readonly previewText?: string;
+  readonly fromName?: string;
+  readonly replyTo?: string;
+  readonly attachments?: readonly EmailAttachmentRef[];
+  /** The layout version the html was rendered through; the editor preview names it. */
+  readonly layout?: RenderedTemplateRef;
+};
+
 export type ChannelContext = {
   readonly db: TenantDb;
   readonly registry: Registry;
@@ -24,8 +39,19 @@ export type ChannelContext = {
   // Chat channels read their per-tenant webhook URL / bot token from it.
   // Absent when no secrets feature/KEK is wired.
   readonly secrets?: SecretsContext | undefined;
+  // Renders a stored mail template, the tenant's own or the system fallback.
+  readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
+  // Reads the bytes behind an attachment ref at send time. Absent when no file storage is wired.
+  readonly readAttachment?: (
+    ref: EmailAttachmentRef,
+    origin?: AttachmentOrigin,
+  ) => Promise<{ readonly content: Uint8Array; readonly contentType: string } | null>;
 };
 
+// "template": the renderer returned the ref from the stored template (own or system). "message":
+// the ref came from notify data, so a caller chose it. Unset means "message".
+export type AttachmentOrigin = "template" | "message";
+
 export type ChannelMessage = {
   readonly notificationType: string;
   readonly title: string;
@@ -49,6 +75,9 @@ export type RenderedMessage = {
   readonly html: string;
   readonly subject: string;
   readonly text?: string;
+  readonly fromName?: string;
+  readonly replyTo?: string;
+  readonly attachments?: readonly EmailAttachmentRef[];
 };
 
 // `mode` decides how the delivery-service dispatches a channel:
@@ -76,21 +105,6 @@ export type DeliveryChannel = {
   ): Promise<ChannelResult>;
 };
 
-// --- Notification Renderer ---
-
-export type RendererInput = {
-  readonly template: string;
-  readonly variables: Readonly<Record<string, unknown>>;
-  readonly locale?: string | undefined;
-};
-
-export type NotificationRenderer = {
-  readonly name: string;
-  render(input: RendererInput): Promise<string>;
-  /** Plain-text version of the same mail; the email channel sends it as the text part of a multipart/alternative mail. */
-  renderText?(input: RendererInput): Promise<string>;
-};
-
 // --- Delivery Log Entry ---
 
 export type DeliveryLogEntry = {
@@ -114,7 +128,9 @@ export type DeliveryService = {
     user: SessionUser,
     tenantId: TenantId,
     jobDispatcher?: NotifyJobDispatcher,
-  ): Promise<NotifyResult>;
+    deliveryDb?: DbConnection,
+    fileProviderResolver?: FileProviderResolver,
+  ): Promise<NotifyDispatched>;
 };
 
 // r.useExtension options-shape: `name` is NOT part of the registration

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

@@ -7,6 +7,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
 import * as z from "zod";
 import { hashUnsubscribeAddress } from "./address-opt-out.js";
@@ -412,8 +413,10 @@ function tokenFromRequestBody(request: SignatureExtraRouteVerifyRequest): string
   }
   if (contentType?.includes("application/json")) {
     try {
-      const parsed = JSON.parse(request.rawBody) as { token?: unknown };
-      return typeof parsed.token === "string" ? parsed.token : undefined;
+      const parsed: unknown = JSON.parse(request.rawBody);
+      return isPlainObject(parsed) && typeof parsed["token"] === "string"
+        ? parsed["token"]
+        : undefined;
     } catch {
       return undefined;
     }

package/packages/bundled-features/src/derivatives-sharp/render.ts

@@ -13,13 +13,10 @@ import type {
 import QRCode from "qrcode";
 import type { OverlayOptions, ResizeOptions, Sharp } from "sharp";
 import sharp from "sharp";
+import { assertNotSvg, SHARP_INPUT_OPTIONS } from "../shared/index.js";
 
 const MIN_SHARP_SIGMA = 0.3;
 const MAX_SHARP_SIGMA = 1000;
-// Above this, a decoded pixel buffer runs into hundreds of MB before any
-// resize even happens — sharp's own default (~268MP) is still large enough
-// to be an OOM primitive for a single request.
-const MAX_INPUT_PIXELS = 100_000_000;
 // Longest output edge a caller may request via `size`/`maxEdge`. Without a
 // cap, `{ maxEdge: 50000 }` allocates a multi-gigabyte buffer per encoder
 // step before any client sees a byte back.
@@ -38,12 +35,6 @@ const MAX_QR_DATA_LENGTH = 1024;
 // camera capture — the AC claims phone-scannable, so an under-sized layer
 // throws instead of caching a silently unusable image.
 const MIN_QR_PIXEL_WIDTH = 160;
-// sequentialRead trades random pixel access for lower peak memory on
-// streamed formats — applied at every decode entry point below since none
-// of them need non-sequential access to the *original* bytes (extract runs
-// against a single already-buffered region per call).
-const SHARP_INPUT_OPTIONS = { limitInputPixels: MAX_INPUT_PIXELS, sequentialRead: true } as const;
-
 function normalizeMimeType(mimeType: string): string {
   return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
 }
@@ -52,18 +43,6 @@ function clampSigma(sigma: number): number {
   return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
 }
 
-// Shared trust boundary for every image byte source this renderer decodes —
-// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
-// alike: a base64 string in a field declaration isn't more trustworthy than
-// an upload just because it came from app code.
-function assertNotSvg(format: string | undefined): void {
-  if (format === "svg") {
-    throw new Error(
-      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
-    );
-  }
-}
-
 function assertValidRegion(region: BlurRegion): void {
   const values = [region.x, region.y, region.width, region.height];
   if (values.some((v) => !Number.isFinite(v)) || region.width <= 0 || region.height <= 0) {

package/packages/bundled-features/src/document-ingest-foundation/pages.ts

@@ -4,6 +4,7 @@
 // the codec here keeps liteparse + recipe consumers lockstep with the
 // entity shape (kumiko-framework#1549/1).
 
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { IngestPage } from "./entity.js";
 
 export function writeIngestPages(pages: readonly IngestPage[]): string {
@@ -28,7 +29,9 @@ function parseJson(raw: string): unknown {
 }
 
 function isIngestPage(value: unknown): value is IngestPage {
-  if (value === null || typeof value !== "object") return false;
-  const page = value as { pageNumber?: unknown; text?: unknown };
-  return typeof page.pageNumber === "number" && typeof page.text === "string";
+  return (
+    isPlainObject(value) &&
+    typeof value["pageNumber"] === "number" &&
+    typeof value["text"] === "string"
+  );
 }

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

@@ -5,6 +5,7 @@ import {
   type RedisClientOptions,
   redisChannelPrefixFromEnv,
 } from "@cosmicdrift/kumiko-framework/redis";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { ToggleSyncSignal } from "./toggle-runtime.js";
 
 // Single fixed channel — unlike the SSE broker there's no per-tenant/
@@ -20,10 +21,9 @@ export type RedisToggleSyncSignal = ToggleSyncSignal & {
 
 function isTogglePayload(value: unknown): value is { featureName: string; enabled: boolean } {
   return (
-    typeof value === "object" &&
-    value !== null &&
-    typeof (value as { featureName?: unknown }).featureName === "string" &&
-    typeof (value as { enabled?: unknown }).enabled === "boolean"
+    isPlainObject(value) &&
+    typeof value["featureName"] === "string" &&
+    typeof value["enabled"] === "boolean"
   );
 }
 

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

@@ -147,7 +147,7 @@ export const publicVariantQuery = defineQueryHandler({
     const spec = resolveFieldVariant(ctx.registry, entityType, fieldName, query.payload.variant);
     if (!spec) return null;
     const result = await derivatives.variant(query.payload.fileRefId, spec, query.payload.variant);
-    const bytes = await files.ref(result.storageKey).read();
+    const bytes = await files.refFromFileRef(result).read();
 
     // ponytail: fully buffered (no streaming), +33% over the wire from
     // base64 — HttpRouteHandlerDeps only exposes {app, systemQuery} (no

package/packages/bundled-features/src/file-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "readFileRefContent reads handed-over files; fileContextForTenant takes the context tenant",
+    "detail": "readFileRefContent, readTemplateResource and the public variant query read bytes through FileContext.refFromFileRef, so a fileRef moved by a tenant handover is readable again. fileContextForTenant gains a `contextTenantId` argument: without a provider resolver it returns undefined for any other tenant instead of the context's files, which are bound to a different key space."
+  },
   {
     "version": "0.292.0",
     "type": "improvement",

package/packages/bundled-features/src/file-foundation/index.ts

@@ -7,3 +7,10 @@ export {
   fileFoundationFeature,
   isFileProviderPlugin,
 } from "./feature.js";
+export {
+  type FileRefContent,
+  FileRefTooLargeError,
+  fileContextForTenant,
+  fileContextFromResolver,
+  readFileRefContent,
+} from "./read-file-ref-content.js";

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -0,0 +1,89 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { isUuid, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFileContext,
+  type FileContext,
+  type FileProviderResolver,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+
+export type FileRefContent = {
+  readonly content: Uint8Array;
+  readonly contentType: string;
+  readonly tenantId: string;
+  readonly size: number;
+};
+
+type FileRefRow = {
+  readonly storageKey: string;
+  readonly mimeType: string;
+  readonly tenantId: string;
+  readonly size: number | bigint | string;
+};
+
+// Tenant-bound on purpose: without a resolver `ctx.files` only reaches the storage of the
+// context's own tenant (`contextTenantId`), so a request for another tenant's files is
+// undefined instead of silently reading through the wrong tenant's storage.
+export function fileContextForTenant(
+  ctx: {
+    readonly _fileProviderResolver?: FileProviderResolver | undefined;
+    readonly files?: FileContext | undefined;
+  },
+  contextTenantId: string,
+  tenantId: string,
+): FileContext | undefined {
+  const resolver = ctx._fileProviderResolver;
+  if (resolver === undefined) return tenantId === contextTenantId ? ctx.files : undefined;
+  return fileContextFromResolver(resolver, tenantId);
+}
+
+export function fileContextFromResolver(
+  resolver: FileProviderResolver,
+  tenantId: string,
+): FileContext {
+  // @cast-boundary engine-payload — tenantId comes from a trusted job payload or session
+  const brandedTenantId = tenantId as TenantId;
+  return createFileContext(() => resolver(brandedTenantId), tenantId);
+}
+
+export class FileRefTooLargeError extends Error {
+  constructor(readonly size: number) {
+    super(`file ref exceeds the size limit (${size} bytes)`);
+  }
+}
+
+// fileName of the row is never used: it is personal data and may be a PII ciphertext.
+export async function readFileRefContent(args: {
+  readonly db: DbRunner | TenantDb;
+  readonly filesForTenant: (tenantId: string) => FileContext | undefined;
+  readonly fileRefId: string;
+  readonly allowedTenantIds: readonly string[];
+  /** Only accept this user's own upload that is not bound to any entity yet. */
+  readonly unclaimedUploadOf?: string;
+  /** Rejects before any bytes are read when the stored size exceeds the limit. */
+  readonly maxBytes?: number;
+}): Promise<FileRefContent | null> {
+  if (!isUuid(args.fileRefId)) return null;
+  const [row] = await selectMany<FileRefRow>(args.db, fileRefsTable, {
+    id: args.fileRefId,
+    tenantId: { in: args.allowedTenantIds },
+    isDeleted: false,
+    ...(args.unclaimedUploadOf !== undefined && {
+      insertedById: args.unclaimedUploadOf,
+      entityType: null,
+      entityId: null,
+    }),
+  });
+  if (row === undefined) return null;
+  const size = Number(row.size);
+  if (args.maxBytes !== undefined && size > args.maxBytes) {
+    throw new FileRefTooLargeError(size);
+  }
+  const files = args.filesForTenant(row.tenantId);
+  if (files === undefined) {
+    throw new Error("readFileRefContent: no file storage is available for the file's tenant");
+  }
+  const content = await files.refFromFileRef(row).read();
+  return { content, contentType: row.mimeType, tenantId: row.tenantId, size };
+}

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Tenant destroy hooks make progress even when the deadline already passed",
+    "detail": "The chunked migration takes a minBatches option and the file destroy hooks process one chunk per tick, so a slow list call no longer makes every run time out empty."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

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

@@ -129,6 +129,7 @@ export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
     },
     maxFailures: 1,
     deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+    minBatches: 1,
     onRowError: (_row, err) => {
       firstFailure = err instanceof Error ? err.message : String(err);
     },
@@ -222,6 +223,9 @@ export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async
       },
       maxFailures: 1,
       deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+      // list() and the survivor lookup above can use up the whole budget; one chunk per tick
+      // still deletes, so the stage never reports "no progress".
+      minBatches: 1,
       onRowError: (_key, err) => {
         firstFailure = err instanceof Error ? err.message : String(err);
       },

package/packages/bundled-features/src/folders/web/folder-manager.tsx

@@ -74,7 +74,10 @@ const loadCollapsed = (): ReadonlySet<string> => {
   if (typeof window === "undefined") return new Set();
   try {
     const raw = window.localStorage.getItem(COLLAPSED_KEY);
-    return new Set(raw ? (JSON.parse(raw) as string[]) : []);
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return new Set(
+      Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === "string") : [],
+    );
   } catch {
     return new Set();
   }
@@ -273,7 +276,7 @@ export function FolderManager({
             setDragOverKey(key);
           },
           onDragLeave: (e: DragEvent<HTMLDivElement>) => {
-            if (!e.currentTarget.contains(e.relatedTarget as Node))
+            if (!(e.relatedTarget instanceof Node && e.currentTarget.contains(e.relatedTarget)))
               setDragOverKey((cur) => (cur === key ? null : cur));
           },
           onDrop: (e: DragEvent<HTMLDivElement>) => {