@cosmicdrift/kumiko-samples 0.381.0 → 0.383.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.381.0",
+  "version": "0.383.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.381.0",
+  "version": "0.383.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Escape-hatch retention loads only needed columns, in keyset pages",
+    "detail": "The retention run groups tenants only over events older than the shortest cutoff, selects id, aggregateId, createdAt and payload, and prunes per 2000-row keyset page instead of loading every row with its full payload."
+  },
   {
     "version": "0.379.0",
     "type": "improvement",

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -76,8 +76,10 @@ async function resolveExplicitRetentionDays(args: {
 const COMPLIANCE_PROFILE_ENTITY = "tenant-compliance-profile";
 const PRUNE_CHUNK_SIZE = 1000;
 const PRUNE_BATCH_SIZE = 5000;
+const SCAN_PAGE_SIZE = 2000;
 
 type AuditEventRow = {
+  readonly id: bigint;
   readonly aggregateId: string;
   readonly tenantId: TenantId;
   readonly createdAt: Temporal.Instant;
@@ -109,12 +111,25 @@ function targetTenantOf(payload: unknown): TenantId | null {
   return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
 }
 
-async function storingTenantIds(db: DbConnection): Promise<readonly TenantId[]> {
+// No tenant's cutoff can be later than the shortest built-in retention: overrides only lengthen it.
+function latestPossibleCutoff(now: Temporal.Instant): Temporal.Instant {
+  const cutoffs = Object.values(COMPLIANCE_PROFILES).map((profile) =>
+    subtractRetentionSpec(now, profile.auditLog.retention),
+  );
+  return cutoffs.reduce((latest, cutoff) =>
+    Temporal.Instant.compare(cutoff, latest) > 0 ? cutoff : latest,
+  );
+}
+
+async function storingTenantIds(
+  db: DbConnection,
+  expirableBefore: Temporal.Instant,
+): Promise<readonly TenantId[]> {
   const groups = await aggregateWhere(
     db,
     eventsTable,
     { measure: { fn: "count" }, groupBy: [{ field: "tenantId" }] },
-    { aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE },
+    { aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE, createdAt: { lt: expirableBefore } },
   );
   return groups.flatMap((group) => {
     const tenantId = parseTenantId(group.keys[0]);
@@ -122,9 +137,24 @@ async function storingTenantIds(db: DbConnection): Promise<readonly TenantId[]>
   });
 }
 
+async function pruneAggregates(db: DbConnection, aggregateIds: readonly string[]): Promise<number> {
+  const now = getTemporal().Now.instant();
+  let deletedCount = 0;
+  for (let i = 0; i < aggregateIds.length; i += PRUNE_CHUNK_SIZE) {
+    const result = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      aggregateIds: aggregateIds.slice(i, i + PRUNE_CHUNK_SIZE),
+      olderThan: now,
+    });
+    deletedCount += result.deletedCount;
+  }
+  return deletedCount;
+}
+
 async function pruneByTenantProfiles(
   db: DbConnection,
   operatorRetentionDays: number | undefined,
+  scanPageSize: number,
 ): Promise<number> {
   const now = getTemporal().Now.instant();
   const operatorFloor =
@@ -142,34 +172,43 @@ async function pruneByTenantProfiles(
 
   // The effective cutoff is never later than the storing tenant's, so only rows older than
   // that one can expire; everything younger stays in the database.
-  const expiredAggregateIds: string[] = [];
-  for (const storingTenantId of await storingTenantIds(db)) {
+  let deletedCount = 0;
+  for (const storingTenantId of await storingTenantIds(db, latestPossibleCutoff(now))) {
     const storeCutoff = await cutoffOf(storingTenantId);
-    const candidates = await selectMany<AuditEventRow>(db, eventsTable, {
-      aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
-      tenantId: storingTenantId,
-      createdAt: { lt: storeCutoff },
-    });
-    for (const row of candidates) {
-      const targetTenantId = targetTenantOf(row.payload);
-      const cutoff = targetTenantId
-        ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
-        : storeCutoff;
-      if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
-        expiredAggregateIds.push(row.aggregateId);
+    // Keyset on id: pruning a page only removes rows at or below the cursor.
+    let afterId: bigint | undefined;
+    for (;;) {
+      const page = await selectMany<AuditEventRow>(
+        db,
+        eventsTable,
+        {
+          aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+          tenantId: storingTenantId,
+          createdAt: { lt: storeCutoff },
+          ...(afterId !== undefined && { id: { gt: afterId } }),
+        },
+        {
+          fields: ["id", "aggregateId", "createdAt", "payload"],
+          orderBy: { col: "id", direction: "asc" },
+          limit: scanPageSize,
+        },
+      );
+      const expiredAggregateIds: string[] = [];
+      for (const row of page) {
+        const targetTenantId = targetTenantOf(row.payload);
+        const cutoff = targetTenantId
+          ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
+          : storeCutoff;
+        if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
+          expiredAggregateIds.push(row.aggregateId);
+        }
       }
+      deletedCount += await pruneAggregates(db, expiredAggregateIds);
+      const lastRow = page[page.length - 1];
+      if (lastRow === undefined || page.length < scanPageSize) break;
+      afterId = lastRow.id;
     }
   }
-
-  let deletedCount = 0;
-  for (let i = 0; i < expiredAggregateIds.length; i += PRUNE_CHUNK_SIZE) {
-    const result = await pruneEvents(db, {
-      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
-      aggregateIds: expiredAggregateIds.slice(i, i + PRUNE_CHUNK_SIZE),
-      olderThan: now,
-    });
-    deletedCount += result.deletedCount;
-  }
   return deletedCount;
 }
 
@@ -199,6 +238,7 @@ export async function runEscapeHatchRetention(args: {
   readonly configResolver: ConfigResolver | undefined;
   readonly userId: string;
   readonly batchSize?: number;
+  readonly scanPageSize?: number;
 }): Promise<{ readonly deletedCount: number }> {
   const { db } = args;
   if (!isDbConnection(db)) {
@@ -211,5 +251,11 @@ export async function runEscapeHatchRetention(args: {
   }
 
   const operatorRetentionDays = await resolveExplicitRetentionDays({ ...args, db });
-  return { deletedCount: await pruneByTenantProfiles(db, operatorRetentionDays) };
+  return {
+    deletedCount: await pruneByTenantProfiles(
+      db,
+      operatorRetentionDays,
+      args.scanPageSize ?? SCAN_PAGE_SIZE,
+    ),
+  };
 }

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Warning when the login limiter falls back to memory in production",
+    "detail": "The in-memory login and MFA rate limiter logs one warning per process in production, because its limits are per replica."
+  },
   {
     "version": "0.379.0",
     "type": "fix",

package/packages/bundled-features/src/cap-overview/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Tenant caps list decrypts only the visible page",
+    "detail": "Without a search and with a sort other than name, the list loads light tenant rows, pages them, and fetches and decrypts names for the current page only. The default name sort and any search still decrypt every tenant, because tenant names are stored encrypted and cannot be sorted or filtered in SQL. Order, total and rows are unchanged."
+  },
   {
     "version": "0.374.0",
     "type": "breaking",

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -16,7 +16,7 @@ import type { CapSpec, CapUsage } from "../types.ts";
 import { capFieldName } from "../web/constants.ts";
 import { computeFraction } from "../web/usage-math.ts";
 
-type TenantRow = { readonly id: string; readonly name: string };
+type TenantRow = { readonly id: string; readonly name?: string };
 type TierAssignmentRow = {
   readonly tenantId: string;
   readonly tier: string;
@@ -54,6 +54,24 @@ const FILTER_OP = z.enum(["eq", "ne", "lt", "gt", "in"]);
 type FilterOp = z.infer<typeof FILTER_OP>;
 
 const SORTABLE_FIELDS = ["name", "tier", "billing"] as const;
+const DEFAULT_SORT_FIELD = "name";
+
+async function withDecryptedPageNames<TRow extends { readonly tenantId: string }>(
+  db: Parameters<typeof selectMany>[0],
+  pageRows: readonly TRow[],
+): Promise<(TRow & { readonly name: string })[]> {
+  const decrypted = await decryptTenantNames(
+    await selectMany<TenantRow>(
+      db,
+      tenantTable,
+      { id: { in: pageRows.map((row) => row.tenantId) } },
+      { fields: ["id", "name"] },
+    ),
+    "cap-overview:tenant-caps:list",
+  );
+  const nameById = new Map(decrypted.map((tenant) => [tenant.id, tenant.name ?? ""]));
+  return pageRows.map((row) => ({ ...row, name: nameById.get(row.tenantId) ?? "" }));
+}
 
 function tenantCapKey(tenantId: string, capId: string): string {
   return JSON.stringify([tenantId, capId]);
@@ -163,11 +181,18 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
         "cap-overview:tenant-caps:list — SystemAdmin platform-wide tenant overview",
       );
 
-      const tenants = await decryptTenantNames(
-        // Destroyed tenants decrypt to the erased sentinel, which a picker or list would show verbatim.
-        await selectMany<TenantRow>(db, tenantTable, { destroyedAt: null }),
-        "cap-overview:tenant-caps:list",
-      );
+      // Names are ciphertext at rest: only a name sort or search has to decrypt every tenant;
+      // otherwise rows stay name-less and just the page is decrypted afterwards.
+      const needsAllNames =
+        (query.payload.sort ?? DEFAULT_SORT_FIELD) === "name" ||
+        (query.payload.search?.trim() ?? "") !== "";
+      const tenants = needsAllNames
+        ? await decryptTenantNames(
+            // Destroyed tenants decrypt to the erased sentinel, which a picker or list would show verbatim.
+            await selectMany<TenantRow>(db, tenantTable, { destroyedAt: null }),
+            "cap-overview:tenant-caps:list",
+          )
+        : await selectMany<TenantRow>(db, tenantTable, { destroyedAt: null }, { fields: ["id"] });
       const assignments = await selectMany<TierAssignmentRow>(db, tierAssignmentTable, {});
       const subscriptions = await selectMany<SubscriptionRow>(db, subscriptionsProjectionTable, {});
 
@@ -182,7 +207,7 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
           return {
             id: tenant.id,
             tenantId: tenant.id,
-            name: tenant.name,
+            name: tenant.name ?? "",
             tier: assignment?.tier ?? "",
             billing: billingLabel(subscriptionByTenant.get(tenant.id), assignment?.source ?? null),
           };
@@ -194,10 +219,13 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
       // tenant/team-list.query.ts. Holds up to tier-engine's documented
       // "single-pass scan" scale (a few thousand tenants); past that the fix
       // is a real combined read-projection.
-      const { rows: page, total } = pageRows(merged, query.payload, {
+      const { rows: pageWithoutNames, total } = pageRows(merged, query.payload, {
         searchFields: ["name"],
-        defaultSort: "name",
+        defaultSort: DEFAULT_SORT_FIELD,
       });
+      const page = needsAllNames
+        ? pageWithoutNames
+        : await withDecryptedPageNames(db, pageWithoutNames);
 
       // Usage is computed only for this page's tenant ids, never for the
       // full tenant set; caps without usageBatch still cost one query per

package/packages/bundled-features/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -34,20 +34,22 @@ export const tenantsMissingProfileQuery = defineQueryHandler({
       "platform operator scans every tenant for a missing compliance-profile selection",
     );
 
-    const tenants = await decryptTenantNames(
-      await db.selectMany<{ id: TenantId; name: string }>(tenantTable, { isEnabled: true }),
-      "compliance-profiles-ops:tenants-missing-profile",
-    );
+    const tenantRows = await db.selectMany<{ id: TenantId; name: string }>(tenantTable, {
+      isEnabled: true,
+    });
     const profileRows = await db.selectMany<{ tenantId: TenantId }>(
       tenantComplianceProfileTable,
       {},
     );
     const tenantIdsWithProfile = new Set(profileRows.map((row) => row.tenantId));
+    // Only tenants that stay in the answer need their name decrypted.
+    const tenants = await decryptTenantNames(
+      tenantRows.filter((tenant) => !tenantIdsWithProfile.has(tenant.id)),
+      "compliance-profiles-ops:tenants-missing-profile",
+    );
 
     return {
-      tenants: tenants
-        .filter((tenant) => !tenantIdsWithProfile.has(tenant.id))
-        .map((tenant) => ({ id: tenant.id, name: tenant.name })),
+      tenants: tenants.map((tenant) => ({ id: tenant.id, name: tenant.name })),
     };
   },
 });

package/packages/bundled-features/src/delivery/attempt-log.ts

@@ -10,7 +10,7 @@ import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_EXTENSION } from "./constants.ts";
 import { deliveryAttemptSchema } from "./events.ts";
-import { maskRecipientAddress } from "./mask-recipient-address.ts";
+import { maskRecipientAddress, maskRecipientAddressOnce } from "./mask-recipient-address.ts";
 import { type DeliveryLogEntry, isDeliveryChannelPlugin } from "./types.ts";
 
 // Unknown channels count as personal: masking is the fail-closed default.
@@ -31,6 +31,27 @@ function loggedAddress(registry: Registry, entry: DeliveryLogEntry): string | nu
     : maskRecipientAddress(entry.recipientAddress);
 }
 
+// Projection-side counterpart of loggedAddress: legacy events were appended with the full address.
+export function rememberConnectionNameChannel(
+  connectionNameChannels: Set<string>,
+  channelName: string,
+  channelOptions: unknown,
+): void {
+  if (isDeliveryChannelPlugin(channelOptions) && channelOptions.addressKind === "connection-name") {
+    connectionNameChannels.add(channelName);
+  }
+}
+
+export function projectedAttemptAddress(
+  connectionNameChannels: ReadonlySet<string>,
+  channel: string,
+  recipientAddress: string | null,
+): string | null {
+  return connectionNameChannels.has(channel)
+    ? recipientAddress
+    : maskRecipientAddressOnce(recipientAddress);
+}
+
 // Shared append + inline-projection write (low-level append() does not
 // auto-fire projections — only the dispatcher/executor paths do).
 async function writeAttemptEvent(

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "fix",
+    "title": "delivery-log projection masks the recipient address",
+    "detail": "The inline projection now masks the address with the same helper as the write path, also on rebuild, so legacy events with a full address no longer reach the attempt log. Already masked addresses and connection-name channels stay unchanged. Swallowed errors in the snapshot save, queue-depth poll and channel pre-resolve now log a scrubbed warning."
+  },
   {
     "version": "0.379.0",
     "type": "improvement",

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

@@ -19,7 +19,11 @@ import {
   createSystemUser,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
-import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import {
+  createFallbackLogger,
+  type Logger,
+  scrubLogText,
+} from "@cosmicdrift/kumiko-framework/logging";
 import {
   assertNotifyTargetsOwnTenant,
   createEscapeHatchReporter,
@@ -652,8 +656,13 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           gates.set(key, gate);
           if (gate !== "open") continue;
           addresses.set(key, await channel.resolve(userId, channelCtx));
-        } catch {
-          // skip: re-resolved (and logged) by deliverToUser
+        } catch (err) {
+          // The per-recipient delivery path resolves again and decides the outcome; this only surfaces the early failure.
+          logError.warn("channel pre-resolve failed", {
+            channel: channel.name,
+            notificationType,
+            error: scrubLogText(err instanceof Error ? err.message : String(err)),
+          });
         }
       }
     }

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

@@ -8,6 +8,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { ConsumerLagError } from "@cosmicdrift/kumiko-framework/pipeline";
 import type * as z from "zod";
+import { projectedAttemptAddress, rememberConnectionNameChannel } from "./attempt-log.ts";
 import { resolveAttemptLogRetentionDays, runAttemptLogRetention } from "./attempt-log-retention.ts";
 import {
   DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
@@ -120,6 +121,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     // drain needed in tests. Chosen over a MultiStreamProjection because
     // delivery-log is a hot read-path for admin/audit UIs that expect
     // read-your-own-write semantics.
+    const connectionNameChannels = new Set<string>();
     r.projection({
       name: "delivery-log",
       source: "deliveryAttempt",
@@ -127,6 +129,11 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       apply: {
         [DELIVERY_ATTEMPT_EVENT]: async (event, tx) => {
           const p = event.payload as z.infer<typeof deliveryAttemptSchema>; // @cast-boundary engine-payload
+          const projectedAddress = projectedAttemptAddress(
+            connectionNameChannels,
+            p.channel,
+            p.recipientAddress,
+          );
           // PK = aggregateId. An async attempt accrues multiple events on one
           // stream (queued → sent/failed): the first INSERTs, later events
           // UPDATE the same row. Events arrive in version order, so the last
@@ -140,7 +147,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
               notificationType: p.notificationType,
               channel: p.channel,
               recipientId: p.recipientId,
-              recipientAddress: p.recipientAddress,
+              recipientAddress: projectedAddress,
               status: p.status,
               error: p.error,
               priority: p.priority,
@@ -149,7 +156,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
             {
               status: p.status,
               error: p.error,
-              recipientAddress: p.recipientAddress,
+              recipientAddress: projectedAddress,
               confirmed: p.confirmed ?? null,
             },
           );
@@ -165,14 +172,10 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       },
     });
 
-    // Extension point: delivery-channels (email/in-app/push). Renderer-
-    // Extension-Point lebt jetzt im `renderer-foundation`-Bundle als
-    // `renderer` (Multi-Kind-Plugin-Contract). delivery hostet keinen
-    // eigenen mehr — channel-email nimmt renderer als direkte
-    // Konstruktor-Option (siehe email-channel.ts), nicht via Extension-
-    // Usage. Migration 2026-05-19.
+    // Connection-name channels address a configured connection, not a person, so they stay unmasked.
     r.extendsRegistrar(DELIVERY_CHANNEL_EXTENSION, {
-      onRegister: () => {},
+      onRegister: (channelName, channelOptions) =>
+        rememberConnectionNameChannel(connectionNameChannels, channelName, channelOptions),
     });
 
     // Async delivery pipeline for queued-mode channels. render decouples the

package/packages/bundled-features/src/delivery/mask-recipient-address.ts

@@ -38,3 +38,17 @@ function maskStructuredOrTail(address: string): string {
   if (address.length < MIN_LENGTH_FOR_VISIBLE_TAIL) return MASK;
   return `${MASK}${address.slice(-VISIBLE_TAIL_LENGTH)}`;
 }
+
+// Masked output is itself a valid input; the projection sees both fresh (already masked) and legacy (full) events.
+function isMaskedRecipientAddress(address: string): boolean {
+  if (address.startsWith(MASK) && address.length <= MASK.length + VISIBLE_TAIL_LENGTH) return true;
+  if (address.endsWith(`/${MASK}`)) return true;
+  return /^[^@]\*\*\*@[^@]+$/.test(address);
+}
+
+// Ciphertext passes through: it is decrypted at read time and a key erase removes it.
+export function maskRecipientAddressOnce(address: string | null): string | null {
+  if (address === null || isPiiCiphertext(address)) return address;
+  if (isMaskedRecipientAddress(address)) return address;
+  return maskPlainAddress(address);
+}

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "Job handlers can return ctx.defer(ms)",
+    "detail": "A handler that returns ctx.defer(ms) moves the queue job to delayed and runs again after ms, like the maxPerTenant defer. It consumes no retry attempt and records no failure, failure log or failed run; the run row of the deferred pass is removed and a tenantVisibleRun record goes back to queued. maxDefers on the job (default 100, shared counter with maxPerTenant defers) bounds the loop; exceeding it fails the run for good (no retry) with a clear message. Inline runs (boot gates) throw. New run-logger hook onJobDeferred, passed through the entrypoint jobs options. JobHandlerFn may now return a JobDeferral. JobContext has a required defer member.",
+    "migration": "add defer to every hand-built JobContext object (tests, seeds), e.g. defer: (delayMs) => ({ kind: \"job-deferral\", delayMs })"
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -59,7 +59,7 @@ export type JobRunLoggerOptions = {
 
 export type JobRunLoggerCallbacks = Pick<
   JobRunnerOptions,
-  "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobQueued" | "onJobDropped"
+  "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobDeferred" | "onJobQueued" | "onJobDropped"
 >;
 
 // Default cap on the bullJobId → runId cache. A worker that starts jobs
@@ -362,6 +362,25 @@ async function recordTenantRunOutcome(
   });
 }
 
+async function requeueTenantRun(
+  db: DbConnection,
+  jobName: string,
+  bullJobId: string,
+  meta: JobMeta,
+): Promise<void> {
+  // skip: job did not opt in to tenantVisibleRun
+  if (!meta.tenantVisibleRun) return;
+  const key = tenantRunKey(jobName, meta.tenantVisibleRun.tenantId, meta.tenantVisibleRun.subject);
+  // skip: system-tenant run, no tenant-scoped query reads it
+  if (!key) return;
+  await updateMany(
+    db,
+    tenantJobRunsTable,
+    { status: "queued", startedAt: null, finishedAt: null, updatedAt: Temporal.Now.instant() },
+    { tenantId: key.tenantId, jobName, bullJobId },
+  );
+}
+
 async function dropTenantRunQueued(
   db: DbConnection,
   jobName: string,
@@ -501,6 +520,20 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       );
     },
 
+    // A deferred run is neither success nor failure: the same job id starts a fresh run later.
+    onJobDeferred: async (jobName: string, bullJobId: string, meta: JobMeta) => {
+      await isolateTenantRunWrite(
+        () => requeueTenantRun(db, jobName, bullJobId, meta),
+        jobName,
+        bullJobId,
+      );
+      const resolved = await resolveRun(bullJobId);
+      // skip: run row already gone (cache evicted and row unreachable)
+      if (!resolved) return;
+      await deleteMany(db, jobRunsTable, { id: resolved.runId });
+      runIdByBullJobId.delete(bullJobId);
+    },
+
     onJobStart: async (jobName: string, bullJobId: string, meta: JobMeta) => {
       await isolateTenantRunWrite(
         () => recordTenantRunStarted(db, jobName, bullJobId, meta),

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "sessionChecker looks up the user and the membership concurrently",
+    "detail": "The session check starts the user lookup together with the session read and the membership lookup together with the last-seen refresh. Results and the fail-open behavior are unchanged; a failed lookup that is not needed no longer raises an unhandled rejection."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

package/packages/bundled-features/src/sessions/session-callbacks.ts

@@ -39,6 +39,15 @@ import {
 // Re-exported so existing `../sessions` importers keep working unchanged.
 export { isPrincipalBlocked };
 
+type SettledLookup<T> = { readonly ok: true; readonly value: T } | { readonly ok: false };
+
+function settleLookup<T>(lookup: Promise<T>): Promise<SettledLookup<T>> {
+  return lookup.then(
+    (value): SettledLookup<T> => ({ ok: true, value }),
+    (): SettledLookup<T> => ({ ok: false }),
+  );
+}
+
 // Why the callbacks live at the raw-DB level rather than going through the
 // dispatcher: session-create/revoke/check run on the hot path of every
 // login and every request. The (createdAt/revokedAt/ip/userAgent) columns
@@ -145,6 +154,14 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
 
     // kumiko-lint-ignore complexity-budget session check + lastSeen refresh on hot path
     async sessionChecker(sid: string, expectedUserId: string): Promise<AuthSessionCheckResult> {
+      // The user lookup is keyed by the JWT's userId, not the session row, so it
+      // overlaps the session read. Settled eagerly: a throwing session read must
+      // not leave this promise as an unhandled rejection.
+      const userLookup = settleLookup(
+        fetchOne<{ status: UserStatus; isDeleted: boolean; roles: string | null }>(db, userTable, {
+          id: expectedUserId,
+        }),
+      );
       const row = await fetchOne<{
         userId: string;
         tenantId: TenantId;
@@ -165,6 +182,15 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
         return "expired";
       }
 
+      // Membership is keyed by the session's tenantId, so it can only start now;
+      // it overlaps the user lookup and the lastSeen refresh.
+      const membershipLookup = settleLookup(
+        fetchOne<{ roles: string | null }>(db, tenantMembershipsTable, {
+          userId: expectedUserId,
+          tenantId: row.tenantId,
+        }),
+      );
+
       // Hourly, not per-request: this check runs on every authenticated
       // request, so a write here has to stay off the hot path.
       const nowMs = Temporal.Now.instant().epochMilliseconds;
@@ -195,16 +221,9 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
       // missing row is a legitimate "no tenant roles" outcome. Both branches
       // return the bare "live" string (no re-derived roles) — the middleware
       // falls back to the JWT's frozen roles claim.
-      let user: { status: UserStatus; isDeleted: boolean; roles: string | null } | undefined;
-      try {
-        user = await fetchOne<{ status: UserStatus; isDeleted: boolean; roles: string | null }>(
-          db,
-          userTable,
-          { id: expectedUserId },
-        );
-      } catch {
-        return "live";
-      }
+      const userResult = await userLookup;
+      if (!userResult.ok) return "live";
+      const user = userResult.value;
       if (!user) return "live";
       if (isPrincipalRowBlocked(user)) return "blocked";
 
@@ -212,16 +231,11 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
       // DB error on the membership read must not lock the user out. A
       // missing row (not a throw) is a valid outcome: the user genuinely has
       // no tenant-scoped roles for row.tenantId, so membershipRoles is [].
-      let membershipRoles: readonly string[];
-      try {
-        const membership = await fetchOne<{ roles: string | null }>(db, tenantMembershipsTable, {
-          userId: expectedUserId,
-          tenantId: row.tenantId,
-        });
-        membershipRoles = membership ? parseRoles(membership.roles) : [];
-      } catch {
-        return "live";
-      }
+      const membershipResult = await membershipLookup;
+      if (!membershipResult.ok) return "live";
+      const membershipRoles = membershipResult.value
+        ? parseRoles(membershipResult.value.roles)
+        : [];
 
       const globalRoles = parseRoles(user.roles);
       const roles = buildSessionRoles(globalRoles, membershipRoles);

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "improvement",
+    "title": "Tenant directory search stops decrypting once the limit is reached",
+    "detail": "Tenant names are encrypted and not in the search index, so the directory search decrypts in small batches and stops after limit matches; the 1000-row scan cap stays. With more matches than the limit, the first matches in key order are returned (sorted by label), not the best alphabetical ones. The missing-profile list drops tenants that already have a profile before decrypting."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/tenant/decrypt-tenant-names.ts

@@ -15,3 +15,28 @@ export async function decryptTenantNames<T extends { readonly name?: unknown }>(
       : row,
   );
 }
+
+// Tenant names are not in the search index (find: "none"), so a name search has to decrypt;
+// stopping at `limit` matches keeps a typed prefix from decrypting the whole scan window.
+export async function takeTenantsMatchingDecryptedName<
+  T extends { readonly id: unknown; readonly name?: unknown },
+>(
+  rows: readonly T[],
+  labelMatches: (label: string) => boolean,
+  limit: number,
+  fallbackRequestId: string,
+): Promise<T[]> {
+  const batchSize = Math.max(limit, KMS_POOL_CONCURRENCY);
+  const matches: T[] = [];
+  for (let start = 0; start < rows.length && matches.length < limit; start += batchSize) {
+    const decrypted = await decryptTenantNames(
+      rows.slice(start, start + batchSize),
+      fallbackRequestId,
+    );
+    for (const row of decrypted) {
+      const label = typeof row.name === "string" ? row.name : String(row.id);
+      if (labelMatches(label)) matches.push(row);
+    }
+  }
+  return matches.slice(0, limit);
+}

package/packages/bundled-features/src/tenant/handlers/tenant-directory.query.ts

@@ -6,7 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { decryptTenantNames } from "../decrypt-tenant-names.ts";
+import { decryptTenantNames, takeTenantsMatchingDecryptedName } from "../decrypt-tenant-names.ts";
 import { tenantTable } from "../schema/tenant.ts";
 import { isSystemAdmin } from "./is-system-admin.ts";
 
@@ -60,18 +60,22 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
     }
     // name is ciphertext at rest, so the SQL page is keyed by the plaintext
     // `key`; label order and search happen in memory after decrypting.
-    const decrypted = await decryptTenantNames(tenants, "tenant:tenant-directory");
-    const labeled = decrypted
+    const needle = search?.toLowerCase();
+    const named =
+      needle === undefined
+        ? await decryptTenantNames(tenants, "tenant:tenant-directory")
+        : await takeTenantsMatchingDecryptedName(
+            tenants,
+            (label) => label.toLowerCase().includes(needle),
+            limit,
+            "tenant:tenant-directory",
+          );
+    const rows = named
       .map((tenant) => {
         const id = String(tenant.id);
         return { id, label: typeof tenant.name === "string" ? tenant.name : id };
       })
       .sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
-    const needle = search?.toLowerCase();
-    const rows =
-      needle === undefined
-        ? labeled
-        : labeled.filter((row) => row.label.toLowerCase().includes(needle)).slice(0, limit);
     return { rows, nextCursor: null };
   },
 });

package/samples/apps/ui-walkthrough/src/features/rental/screens.ts

@@ -171,7 +171,13 @@ export const leaseDetailScreen: ProjectionDetailScreenDefinition = {
     statusToneField: "status",
     statusTones: { active: "ok", terminated: "bad" },
   },
-  metrics: ["grundmiete", "beginn", "kuendigungsfrist", "zahltag", "mieter"],
+  metrics: [
+    { field: "grundmiete", label: "rental:entity:lease:field:grundmiete" },
+    { field: "beginn", label: "rental:entity:lease:field:beginn" },
+    { field: "kuendigungsfrist", label: "rental:entity:lease:field:kuendigungsfrist" },
+    { field: "zahltag", label: "rental:entity:lease:field:zahltag" },
+    { field: "mieter", label: "rental:entity:lease:field:mieter" },
+  ],
   fieldLabels: {
     grundmiete: "rental:entity:lease:field:grundmiete",
     beginn: "rental:entity:lease:field:beginn",

package/samples/recipes/api-worker-split/README.md

@@ -54,6 +54,14 @@ With only the API running, `read_orders` gains the row but
 `read_order_activity` stays empty. Start the worker and both the activity
 row and the `read_fulfillments` row appear.
 
+## Deferring a job
+
+`process-order` returns `context.defer(ms)` while the (simulated) carrier is busy. The job
+is re-run after `ms` on the same queue job: no retry attempt is used, no failure is logged
+or recorded, and the run log shows only the runs that actually executed. `maxDefers`
+(default 100) bounds it; beyond that the run fails. It needs a queued run: an inline boot
+gate throws.
+
 ## Test
 
 Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).

package/samples/recipes/api-worker-split/src/feature.ts

@@ -84,6 +84,13 @@ export function setOrderFulfillWrite(fn: FulfillWrite): void {
   fulfillWrite = fn;
 }
 
+let carrierRetryAfterMs: () => number = () => 0;
+
+/** Stand-in for a rate-limited carrier API: ms until it accepts work again, 0 when free. */
+export function setCarrierRetryAfter(fn: () => number): void {
+  carrierRetryAfterMs = fn;
+}
+
 // Job payloads arrive as `Record<string, unknown>` (JobHandlerFn) — an
 // unchecked `as string` cast here would let a missing/non-string field
 // through silently, writing `orderKey: undefined` / `label: "label-
@@ -123,6 +130,9 @@ export function createApiWorkerSplitFeature() {
           );
         }
         const { customerName } = processOrderPayloadSchema.parse(payload);
+        // Busy is not a failure: ctx.defer re-runs the job later without burning a retry.
+        const retryAfterMs = carrierRetryAfterMs();
+        if (retryAfterMs > 0) return context.defer(retryAfterMs);
         const result = await fulfillWrite({
           handlerQn: "orders:write:fulfillment:create",
           payload: {

package/samples/recipes/record-detail-layout/README.md

@@ -5,12 +5,12 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
 
 ## What it shows
 
-- `header` (title/subtitle/status) and `metrics` (labeled via `fieldLabels`)
+- `header` (title/subtitle/status) and `metrics` (each with its own i18n `label`)
   rendered from the columns of the screen's own query row
 - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
   and one `fields` tab (master data) — each `relatedList` runs its own query
 - boot-validator catching two common author mistakes: a `metrics` entry
-  without a `fieldLabels` override, and a `tabs` layout with fewer than two
+  with an empty `label`, and a `tabs` layout with fewer than two
   sections
 
 ## Source

package/samples/recipes/record-detail-layout/src/feature.ts

@@ -3,8 +3,8 @@
 //   1. `header` renders the query row's customer/order/status columns above
 //      the layout — the identity a support agent scans first.
 //   2. `metrics` renders a labeled band of key numbers from the same row —
-//      labels come from `fieldLabels`, there is no fallback to the raw
-//      column name.
+//      each metric carries its own i18n `label`, there is no fallback to the
+//      raw column name.
 //   3. `layout.mode: "tabs"` splits the record into four tabs: two
 //      `relatedList` sections (own query, own pagination, mounts only when
 //      active), one `fields` section (master data from the detail row), and
@@ -76,13 +76,12 @@ export function createOrderDeskFeature(): FeatureDefinition {
       type: "projectionDetail",
       query: "order-desk:query:order:detail",
       header: { title: "customerName", subtitle: "orderNumber", status: "status" },
-      metrics: ["totalAmount", "outstandingAmount", "itemCount", "placedAt"],
-      fieldLabels: {
-        totalAmount: "order-desk.metric.totalAmount",
-        outstandingAmount: "order-desk.metric.outstandingAmount",
-        itemCount: "order-desk.metric.itemCount",
-        placedAt: "order-desk.metric.placedAt",
-      },
+      metrics: [
+        { field: "totalAmount", label: "order-desk.metric.totalAmount" },
+        { field: "outstandingAmount", label: "order-desk.metric.outstandingAmount" },
+        { field: "itemCount", label: "order-desk.metric.itemCount" },
+        { field: "placedAt", label: "order-desk.metric.placedAt" },
+      ],
       layout: {
         mode: "tabs",
         sections: [