@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -3,8 +3,9 @@ import { createTenantDb, type DbConnection, type TenantDb } from "@cosmicdrift/k
 import type { ConfigAccessor, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { readFileRefContent } from "../file-foundation/index.js";
+import { type FileRefContent, readFileRefContent } from "../file-foundation/index.js";
 import {
   collectRendererPlugins,
   createRendererFoundationApi,
@@ -40,7 +41,10 @@ export function createTemplateMailRenderer(
       html: response.html,
       text: response.text,
       ...(response.previewText !== undefined && { previewText: response.previewText }),
+      ...(response.fromName !== undefined && { fromName: response.fromName }),
+      ...(response.replyTo !== undefined && { replyTo: response.replyTo }),
       ...(response.attachments !== undefined && { attachments: response.attachments }),
+      ...(response.layout !== undefined && { layout: response.layout }),
     };
   };
 }
@@ -82,6 +86,22 @@ function createPdfRenderer(
   };
 }
 
+// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+async function readInlineImageOrNull(
+  fileRefId: string,
+  read: () => Promise<FileRefContent | null>,
+): Promise<FileRefContent | null> {
+  try {
+    return await read();
+  } catch (err) {
+    createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
+      fileRefId,
+      errorName: err instanceof Error ? err.name : typeof err,
+    });
+    return null;
+  }
+}
+
 // Inline images and file attachments the renderer took from a template may come from the system
 // tenant (system template or tenant override of one). A file ref from notify data stays limited to
 // the job's own tenant, since a caller picks it. Inline content that is not an image is dropped, so
@@ -96,13 +116,16 @@ export function createEmailAttachmentReader(
   const renderPdf = createPdfRenderer(db, registry, tenantId, config, filesForTenant);
   return async (ref: EmailAttachmentRef, origin: AttachmentOrigin = "message") => {
     if (ref.kind === "rendered-pdf") return renderPdf(ref);
-    const found = await readFileRefContent({
-      db,
-      filesForTenant,
-      fileRefId: ref.fileRefId,
-      allowedTenantIds:
-        ref.kind === "file" && origin === "message" ? [tenantId] : [tenantId, SYSTEM_TENANT_ID],
-    });
+    const readRef = () =>
+      readFileRefContent({
+        db,
+        filesForTenant,
+        fileRefId: ref.fileRefId,
+        allowedTenantIds:
+          ref.kind === "file" && origin === "message" ? [tenantId] : [tenantId, SYSTEM_TENANT_ID],
+      });
+    const found =
+      ref.kind === "inline" ? await readInlineImageOrNull(ref.fileRefId, readRef) : await readRef();
     if (found === null) return null;
     if (ref.kind === "inline" && !found.contentType.startsWith(INLINE_IMAGE_CONTENT_TYPE_PREFIX)) {
       return null;

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

@@ -205,14 +205,23 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
   // A key that guarded nothing must not turn the caller's retry into a skipped duplicate.
   // Partial success keeps it: a retry would re-send to those who got it.
+  // A failing release is logged and swallowed: it must neither replace the dispatch error the
+  // caller retries on nor fail a notify() that already dispatched.
   async function releaseIdempotencyIfNothingDelivered(
     tenantId: TenantId,
     key: string | undefined,
     run: NotifyRun,
+    notificationType: string,
   ): Promise<void> {
     // skip: no key claimed, or a recipient already got the notification
     if (!key || run.deliveries.some(isDeliveredOrQueued)) return;
-    await idemRedis?.del(deliveryIdempotencyRedisKey(tenantId, key));
+    try {
+      await idemRedis?.del(deliveryIdempotencyRedisKey(tenantId, key));
+    } catch (releaseErr) {
+      logError.warn(`idempotency key release failed: ${redactedMessageOf(releaseErr)}`, {
+        notificationType,
+      });
+    }
   }
 
   // Only a single-channel route lets the queued job free the key on terminal failure
@@ -508,29 +517,53 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
   const recipientChannelKey = (userId: string, channelName: string) => `${userId}|${channelName}`;
 
-  async function isChannelDeliverable(
+  type ChannelGate = "open" | "channel_disabled" | "preference_disabled" | "rate_limited";
+  type PrefetchedRecipients = {
+    readonly addresses: ReadonlyMap<string, string | null>;
+    readonly gates: ReadonlyMap<string, ChannelGate>;
+  };
+
+  // Kill switch, then the user's preference, then the rate limit — the order deliverToUser reports
+  // skips in. The rate limit consumes a token, so each recipient/channel pair is evaluated once.
+  async function evaluateChannelGate(
     run: NotifyRun,
     userId: string,
     tenantId: TenantId,
     notificationType: string,
     channelName: string,
-  ): Promise<boolean> {
-    if (isChannelKilled && (await isChannelKilled(tenantId, channelName))) return false;
-    return isChannelEnabled(run, userId, tenantId, notificationType, channelName);
+    priority: NotifyPriority,
+  ): Promise<ChannelGate> {
+    if (isChannelKilled && (await isChannelKilled(tenantId, channelName))) {
+      return "channel_disabled";
+    }
+    // Critical priority skips the preference check
+    if (
+      priority !== "critical" &&
+      !(await isChannelEnabled(run, userId, tenantId, notificationType, channelName))
+    ) {
+      return "preference_disabled";
+    }
+    if (rateLimit && !(await checkRateLimit(rateLimit, tenantId, channelName))) {
+      return "rate_limited";
+    }
+    return "open";
   }
 
   // Resolves every user's channel addresses up front so the opt-out lookup can
-  // cover them all at once. A resolve that throws stays out of the map: the
-  // delivery loop resolves it again and reports channel_error as before.
-  // Channels the kill switch or the user's preferences disable are never resolved
-  // here: resolve may have side effects and deliverToUser skips those channels.
-  async function prefetchUserAddresses(
+  // cover them all at once. A resolve that throws stays out of the address map:
+  // the delivery loop resolves it again and reports channel_error as before.
+  // Channels that are gated (kill switch, preferences, rate limit) are never resolved
+  // here: resolve may have side effects and deliverToUser skips those channels. The
+  // gate verdict is kept so deliverToUser does not query it a second time.
+  async function prefetchRecipients(
     run: NotifyRun,
     userIds: readonly string[],
     tenantId: TenantId,
     notificationType: string,
-  ): Promise<Map<string, string | null>> {
+    priority: NotifyPriority,
+  ): Promise<PrefetchedRecipients> {
     const addresses = new Map<string, string | null>();
+    const gates = new Map<string, ChannelGate>();
     const channelCtx = buildChannelContext(
       run.db,
       registry,
@@ -543,22 +576,25 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     for (const userId of userIds) {
       for (const channel of channels) {
         if (!channel.resolve) continue;
+        const key = recipientChannelKey(userId, channel.name);
         try {
-          if (
-            !(await isChannelDeliverable(run, userId, tenantId, notificationType, channel.name))
-          ) {
-            continue;
-          }
-          addresses.set(
-            recipientChannelKey(userId, channel.name),
-            await channel.resolve(userId, channelCtx),
+          const gate = await evaluateChannelGate(
+            run,
+            userId,
+            tenantId,
+            notificationType,
+            channel.name,
+            priority,
           );
+          gates.set(key, gate);
+          if (gate !== "open") continue;
+          addresses.set(key, await channel.resolve(userId, channelCtx));
         } catch {
           // skip: re-resolved (and logged) by deliverToUser
         }
       }
     }
-    return addresses;
+    return { addresses, gates };
   }
 
   // Check if user has disabled this notification+channel combo.
@@ -605,7 +641,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantId: TenantId,
     priority: NotifyPriority,
     run: NotifyRun,
-    prefetchedAddresses: ReadonlyMap<string, string | null>,
+    prefetched: PrefetchedRecipients,
     suppressed: ReadonlySet<AddressOptOutKey>,
   ): Promise<void> {
     const channelCtx = buildChannelContext(
@@ -624,70 +660,35 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
       const message = buildMessage(notificationType, data, channel.name, run.locale);
 
-      // Kill switch: tenant admin disabled this channel entirely
-      if (isChannelKilled) {
-        const killed = await isChannelKilled(tenantId, channel.name);
-        if (killed) {
-          await logDelivery(run, {
-            tenantId,
-            notificationType,
-            channel: channel.name,
-            recipientId: userId,
-            recipientAddress: null,
-            status: "skipped",
-            error: "channel_disabled",
-            priority,
-          });
-          continue;
-        }
-      }
-
-      // Check preferences (critical priority skips preference check)
-      if (priority !== "critical") {
-        const enabled = await isChannelEnabled(
+      const prefetchKey = recipientChannelKey(userId, channel.name);
+      const gate =
+        prefetched.gates.get(prefetchKey) ??
+        (await evaluateChannelGate(
           run,
           userId,
           tenantId,
           notificationType,
           channel.name,
-        );
-        if (!enabled) {
-          await logDelivery(run, {
-            tenantId,
-            notificationType,
-            channel: channel.name,
-            recipientId: userId,
-            recipientAddress: null,
-            status: "skipped",
-            error: "preference_disabled",
-            priority,
-          });
-          continue;
-        }
-      }
-
-      // Rate limiting
-      if (rateLimit) {
-        const allowed = await checkRateLimit(rateLimit, tenantId, channel.name);
-        if (!allowed) {
-          await logDelivery(run, {
-            tenantId,
-            notificationType,
-            channel: channel.name,
-            recipientId: userId,
-            recipientAddress: null,
-            status: "skipped",
-            error: "rate_limited",
-            priority,
-          });
-          continue;
-        }
+          priority,
+        ));
+      if (gate !== "open") {
+        await logDelivery(run, {
+          tenantId,
+          notificationType,
+          channel: channel.name,
+          recipientId: userId,
+          recipientAddress: null,
+          status: "skipped",
+          error: gate,
+          priority,
+        });
+        continue;
       }
 
       try {
-        const prefetchKey = recipientChannelKey(userId, channel.name);
-        const address = prefetchedAddresses.has(prefetchKey)
-          ? prefetchedAddresses.get(prefetchKey)
+        const wasPrefetched = prefetched.addresses.has(prefetchKey);
+        const address = wasPrefetched
+          ? prefetched.addresses.get(prefetchKey)
           : await channel.resolve(userId, channelCtx);
         if (!address) {
           await logDelivery(run, {
@@ -703,7 +704,14 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           continue;
         }
 
-        if (priority !== "critical" && isAddressSuppressed(suppressed, address, channel.name)) {
+        // A fallback resolve yields an address the batched opt-out lookup never covered.
+        const suppressedForAddress = wasPrefetched
+          ? suppressed
+          : await loadSuppressedAddresses(run, tenantId, notificationType, priority, [address]);
+        if (
+          priority !== "critical" &&
+          isAddressSuppressed(suppressedForAddress, address, channel.name)
+        ) {
           await logDelivery(run, {
             tenantId,
             notificationType,
@@ -878,16 +886,16 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         userIds = to;
       }
 
-      const prefetchedAddresses =
+      const prefetched: PrefetchedRecipients =
         priority === "critical"
-          ? new Map<string, string | null>()
-          : await prefetchUserAddresses(run, userIds, tenantId, notificationType);
+          ? { addresses: new Map(), gates: new Map() }
+          : await prefetchRecipients(run, userIds, tenantId, notificationType, priority);
       const suppressed = await loadSuppressedAddresses(
         run,
         tenantId,
         notificationType,
         priority,
-        [...prefetchedAddresses.values()].filter((address): address is string => !!address),
+        [...prefetched.addresses.values()].filter((address): address is string => !!address),
       );
 
       for (const userId of userIds) {
@@ -898,7 +906,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           tenantId,
           priority,
           run,
-          prefetchedAddresses,
+          prefetched,
           suppressed,
         );
       }
@@ -955,17 +963,10 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       try {
         await dispatchNotification(notificationType, options, tenantId, priority, run);
       } catch (err) {
-        // A failing release must not replace the dispatch error the caller retries on.
-        await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run).catch(
-          (releaseErr: unknown) => {
-            logError.warn(`idempotency key release failed: ${redactedMessageOf(releaseErr)}`, {
-              notificationType,
-            });
-          },
-        );
+        await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run, notificationType);
         throw err;
       }
-      await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run);
+      await releaseIdempotencyIfNothingDelivered(tenantId, idempotencyKey, run, notificationType);
       return dispatched(run);
     },
   };

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

@@ -1,6 +1,7 @@
 export { sanitizePdfAttachmentFileName } from "../shared/index.js";
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
 export {
+  DELIVERY_ENVELOPE_DATA_KEYS,
   type EmailAttachmentRef,
   emailAttachmentRefSchema,
   type FileAttachmentRef,
@@ -12,6 +13,7 @@ export {
   type RenderedPdfAttachmentRef,
   renderedPdfAttachmentRefSchema,
   toAttachmentRef,
+  withoutDeliveryEnvelopeKeys,
 } from "./attachment-ref.js";
 export {
   type AttemptLogRetentionOptions,

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

@@ -59,6 +59,8 @@ const sendJobPayloadSchema = renderJobPayloadSchema.extend({
       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(),
@@ -96,6 +98,8 @@ function toSendRendered(
     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),
     }),
@@ -138,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,
@@ -162,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.
@@ -184,7 +211,6 @@ async function failAttempt(
     p.deliveryAttemptId,
     entryFor(p, "failed", code, p.address),
   );
-  await releaseIdempotencyOnTerminalFailure(ctx, p);
   throw new Error(code);
 }
 
@@ -193,6 +219,10 @@ 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);
@@ -203,7 +233,7 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
     tenantId,
     ctx.secrets,
     ctx.config,
-    (fileTenantId) => fileContextForTenant(ctx, fileTenantId),
+    (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
   );
 
   let rendered: RenderedMessage;
@@ -225,13 +255,17 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
   } 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);
@@ -242,7 +276,7 @@ export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
     tenantId,
     ctx.secrets,
     ctx.config,
-    (fileTenantId) => fileContextForTenant(ctx, fileTenantId),
+    (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
   );
 
   try {
@@ -259,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/types.ts

@@ -13,7 +13,7 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { MailPayload } from "../renderer-foundation/index.js";
+import type { MailPayload, RenderedTemplateRef } from "../renderer-foundation/index.js";
 import type { EmailAttachmentRef } from "./attachment-ref.js";
 import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 
@@ -24,7 +24,11 @@ export type RenderedMail = {
   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 = {
@@ -71,6 +75,8 @@ export type RenderedMessage = {
   readonly html: string;
   readonly subject: string;
   readonly text?: string;
+  readonly fromName?: string;
+  readonly replyTo?: string;
   readonly attachments?: readonly EmailAttachmentRef[];
 };
 

package/packages/bundled-features/src/document-ingest-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Ingest events: correlate by event type and payload.fileRefId",
+    "detail": "New documentIngest events live on their own stream while older ones stay on the fileRef stream (aggregateId = fileRefId). Consumers must not correlate by aggregateId or the fileRef stream version."
+  },
   {
     "version": "0.362.0",
     "type": "fix",

package/packages/bundled-features/src/feature-toggles/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Overlapping toggle refreshes no longer drop a flip, and the runtime can reuse the server cache-sync bus",
+    "detail": "initialize() and refresh() now run one snapshot load at a time, so a flip applied while a second load is in flight is kept instead of being overwritten by older rows. createFeatureToggleRuntime takes an optional fourth cacheSyncBus argument; with it no second bus (and no extra Redis connections) is created and close() leaves the shared bus open.",
+    "migration": "Pass the server's cache-sync bus as the fourth argument of createFeatureToggleRuntime to avoid the additional Redis publisher and subscriber connections of the default bus; without it the runtime still builds and closes its own bus."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

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

@@ -7,6 +7,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import {
+  type CacheSyncBus,
   type ClosableCacheSyncBus,
   createDefaultCacheSyncBus,
 } from "@cosmicdrift/kumiko-framework/redis";
@@ -40,9 +41,11 @@ export type ToggleSyncSignal = {
 // per-instance behavior for the only process there is.
 export class GlobalFeatureToggleRuntime {
   private snapshot = new Map<string, boolean>();
-  // 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.
-  private appliedDuringLoad: Map<string, boolean> | undefined;
+  // One buffer per requested load, open from the call until its SELECT finished: the SELECT
+  // may have started before a flip committed, so its rows can be older than the flips collected.
+  private readonly pendingFlipBuffers = new Set<Map<string, boolean>>();
+  // Loads run one at a time so the older rows of one cannot overwrite the result of another.
+  private loadInFlight: Promise<void> = Promise.resolve();
 
   constructor(
     private readonly db: DbConnection,
@@ -69,10 +72,16 @@ export class GlobalFeatureToggleRuntime {
     await this.ownedBus?.close();
   }
 
-  async initialize(): Promise<void> {
-    type Row = { featureName: string; enabled: boolean };
+  initialize(): Promise<void> {
     const pendingFlips = new Map<string, boolean>();
-    this.appliedDuringLoad = pendingFlips;
+    this.pendingFlipBuffers.add(pendingFlips);
+    const load = this.loadInFlight.then(() => this.loadSnapshot(pendingFlips));
+    this.loadInFlight = load.catch(() => undefined);
+    return load;
+  }
+
+  private async loadSnapshot(pendingFlips: Map<string, boolean>): Promise<void> {
+    type Row = { featureName: string; enabled: boolean };
     try {
       const rows = await selectMany<Row>(this.db, globalFeatureStateTable);
       this.snapshot = new Map([
@@ -80,7 +89,7 @@ export class GlobalFeatureToggleRuntime {
         ...pendingFlips,
       ]);
     } finally {
-      this.appliedDuringLoad = undefined;
+      this.pendingFlipBuffers.delete(pendingFlips);
     }
   }
 
@@ -98,7 +107,7 @@ export class GlobalFeatureToggleRuntime {
   // lock. Kept alongside refresh() so both options are explicit.
   apply(featureName: string, enabled: boolean): void {
     this.snapshot.set(featureName, enabled);
-    this.appliedDuringLoad?.set(featureName, enabled);
+    for (const pendingFlips of this.pendingFlipBuffers) pendingFlips.set(featureName, enabled);
   }
 
   // Called by the toggle-cache-sync MSP handler (feature.ts) — the one
@@ -144,15 +153,20 @@ export class GlobalFeatureToggleRuntime {
 
 // 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.
+// syncSignal the signal runs on the given cacheSyncBus or, failing that, on a bus the runtime
+// creates itself (Redis-backed when REDIS_URL is set, process-local otherwise). close() releases
+// only a bus the runtime created.
 export async function createFeatureToggleRuntime(
   db: DbConnection,
   registry: Registry,
   syncSignal?: ToggleSyncSignal,
+  // The server's own bus (the one handed to the dispatcher): reusing it avoids a second set of
+  // Redis connections that nothing closes at shutdown.
+  cacheSyncBus?: CacheSyncBus,
 ): Promise<GlobalFeatureToggleRuntime> {
-  const ownedBus = syncSignal ? undefined : createDefaultCacheSyncBus();
-  const signal = syncSignal ?? (ownedBus ? createCacheSyncToggleSignal(ownedBus) : undefined);
+  const ownedBus = syncSignal || cacheSyncBus ? undefined : createDefaultCacheSyncBus();
+  const sharedBus = cacheSyncBus ?? ownedBus;
+  const signal = syncSignal ?? (sharedBus ? createCacheSyncToggleSignal(sharedBus) : undefined);
   const runtime = new GlobalFeatureToggleRuntime(db, registry, signal, ownedBus);
   try {
     await runtime.initialize();

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