@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

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

@@ -22,7 +22,11 @@ import { hashUnsubscribeAddress } from "./address-opt-out.js";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DELIVERY_CHANNEL_EXTENSION, DeliveryJobs, deliveryPriorityRank } from "./constants.js";
-import { isAddressOptedOut } from "./db/queries/address-opt-outs.js";
+import {
+  type AddressOptOutKey,
+  addressOptOutKey,
+  selectOptedOutAddresses,
+} from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
 import {
   type ChannelContext,
@@ -411,16 +415,74 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
   // Shared by deliverToUser (resolved account address) and deliverDirect (a
   // route address with no user account) — same suppression rule either way:
-  // no blind-index key configured means no hash, so nothing to look up.
-  async function isAddressSuppressed(
+  // no blind-index key configured means no hash, so nothing to look up. One
+  // query per notify() call, not per recipient and channel.
+  async function loadSuppressedAddresses(
+    tenantId: TenantId,
+    notificationType: string,
+    priority: NotifyPriority,
+    addresses: Iterable<string>,
+  ): Promise<ReadonlySet<AddressOptOutKey>> {
+    // Critical priority skips address opt-outs, same rule as user preferences.
+    if (priority === "critical") return new Set();
+    const addressHashes = new Set<string>();
+    for (const address of addresses) {
+      const addressHash = hashUnsubscribeAddress(address);
+      if (addressHash !== undefined) addressHashes.add(addressHash);
+    }
+    return selectOptedOutAddresses(db, tenantId, notificationType, [...addressHashes]);
+  }
+
+  function isAddressSuppressed(
+    suppressed: ReadonlySet<AddressOptOutKey>,
     address: string,
+    channelName: string,
+  ): boolean {
+    const addressHash = hashUnsubscribeAddress(address);
+    return addressHash !== undefined && suppressed.has(addressOptOutKey(addressHash, channelName));
+  }
+
+  const recipientChannelKey = (userId: string, channelName: string) => `${userId}|${channelName}`;
+
+  async function isChannelDeliverable(
+    userId: string,
     tenantId: TenantId,
     notificationType: string,
     channelName: string,
   ): Promise<boolean> {
-    const addressHash = hashUnsubscribeAddress(address);
-    if (addressHash === undefined) return false;
-    return isAddressOptedOut(db, tenantId, addressHash, notificationType, channelName);
+    if (isChannelKilled && (await isChannelKilled(tenantId, channelName))) return false;
+    return isChannelEnabled(userId, tenantId, notificationType, channelName);
+  }
+
+  // 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(
+    userIds: readonly string[],
+    tenantId: TenantId,
+    notificationType: string,
+  ): Promise<Map<string, string | null>> {
+    const addresses = new Map<string, string | null>();
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    for (const userId of userIds) {
+      for (const channel of channels) {
+        if (!channel.resolve) continue;
+        try {
+          if (!(await isChannelDeliverable(userId, tenantId, notificationType, channel.name))) {
+            continue;
+          }
+          addresses.set(
+            recipientChannelKey(userId, channel.name),
+            await channel.resolve(userId, channelCtx),
+          );
+        } catch {
+          // skip: re-resolved (and logged) by deliverToUser
+        }
+      }
+    }
+    return addresses;
   }
 
   // Check if user has disabled this notification+channel combo.
@@ -466,6 +528,8 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantId: TenantId,
     priority: NotifyPriority,
     run: NotifyRun,
+    prefetchedAddresses: ReadonlyMap<string, string | null>,
+    suppressed: ReadonlySet<AddressOptOutKey>,
   ): Promise<void> {
     const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
 
@@ -530,7 +594,10 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       }
 
       try {
-        const address = await channel.resolve(userId, channelCtx);
+        const prefetchKey = recipientChannelKey(userId, channel.name);
+        const address = prefetchedAddresses.has(prefetchKey)
+          ? prefetchedAddresses.get(prefetchKey)
+          : await channel.resolve(userId, channelCtx);
         if (!address) {
           await logDelivery(run, {
             tenantId,
@@ -545,10 +612,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           continue;
         }
 
-        if (
-          priority !== "critical" &&
-          (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
-        ) {
+        if (priority !== "critical" && isAddressSuppressed(suppressed, address, channel.name)) {
           await logDelivery(run, {
             tenantId,
             notificationType,
@@ -602,6 +666,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     run: NotifyRun,
   ): Promise<void> {
     const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId, secrets);
+    const suppressed = await loadSuppressedAddresses(
+      tenantId,
+      notificationType,
+      priority,
+      Object.values(route),
+    );
 
     // Direct routing skips preferences (no user account) but NOT rate limit
     // — direct sends can still be abused (webhook replays, test harnesses).
@@ -612,10 +682,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
 
       // Address opt-out (critical priority skips it, same rule as user
       // preferences).
-      if (
-        priority !== "critical" &&
-        (await isAddressSuppressed(address, tenantId, notificationType, channel.name))
-      ) {
+      if (priority !== "critical" && isAddressSuppressed(suppressed, address, channel.name)) {
         await logDelivery(run, {
           tenantId,
           notificationType,
@@ -729,8 +796,28 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           userIds = to;
         }
 
+        const prefetchedAddresses =
+          priority === "critical"
+            ? new Map<string, string | null>()
+            : await prefetchUserAddresses(userIds, tenantId, notificationType);
+        const suppressed = await loadSuppressedAddresses(
+          tenantId,
+          notificationType,
+          priority,
+          [...prefetchedAddresses.values()].filter((address): address is string => !!address),
+        );
+
         for (const userId of userIds) {
-          await deliverToUser(userId, notificationType, data, tenantId, priority, run);
+          await deliverToUser(
+            userId,
+            notificationType,
+            data,
+            tenantId,
+            priority,
+            run,
+            prefetchedAddresses,
+            suppressed,
+          );
         }
       }
       return { deliveries: run.deliveries };

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";