@k2b/cloud 0.36.0 → 0.38.0

package/src/styles/global.css

@@ -79,8 +79,8 @@ html:has(.cloud-app-canvas[data-layout-full-page="true"]) {
 /* The authenticated rail is part of the canvas. Keeping it transparent also
    covers shell-only routes such as 404 pages that have no app workspace. */
 .cloud-app-canvas > .layout-rail {
-  width: calc(2.5rem + var(--ui-space-shell));
-  margin-inline-start: calc(-1 * var(--ui-space-shell));
+  width: calc(3.5rem + env(safe-area-inset-left, 0px));
+  padding-left: env(safe-area-inset-left, 0px);
   background-color: transparent !important;
   background-image: none !important;
 }
@@ -294,11 +294,13 @@ solid-island {
 }
 
 /* Cloud has three shell modes. Phones, below md, get the header and no rail.
-   From md, signed-in people get the rail instead of the header: up to 2xl the
-   app area meets the window's top, right and bottom edges, and from 2xl it is
-   a card with the shell spacing. Anonymous pages keep the header and the card
-   from md. */
-@media (max-width: 767px) {
+   From md, signed-in people get the 56 px rail instead of the header: up to
+   1023 px the app area meets the window's top, right and bottom edges, and
+   from 1024 px it is a card beside the rail. Anonymous pages keep the header
+   and the card from md. Each query is the exact opposite of the next one, so
+   every width, also a fractional one under browser zoom, falls into exactly
+   one mode. */
+@media not all and (min-width: 768px) {
   .cloud-app-canvas {
     padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px);
   }
@@ -360,35 +362,162 @@ solid-island {
    The rail and the app area reach the window's edges also where the installed
    app reports safe areas, such as the status bar and the home indicator. Their
    own surfaces fill the insets, and their content stays inside them. */
-@media (min-width: 768px) and (max-width: 1535px) {
+@media (min-width: 768px) {
+  @media not all and (min-width: 1024px) {
+    .cloud-app-canvas[data-layout-authenticated] {
+      padding: 0;
+    }
+    .cloud-app-canvas[data-layout-authenticated] > .layout-rail {
+      padding-top: env(safe-area-inset-top, 0px);
+      padding-bottom: calc(var(--ui-space-shell) + env(safe-area-inset-bottom, 0px));
+    }
+    .cloud-app-canvas[data-layout-authenticated] > .layout-shell-content {
+      gap: 0;
+      padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) 0 0;
+      background: var(--k2b-surface);
+    }
+    /* A regular page scrolls `main`, so its end clears the home indicator. A
+       workspace reaches the bottom edge and clears it inside its own surfaces. */
+    .cloud-app-canvas[data-layout-authenticated] .layout-content-main:not(:has(.k2b-app-workspace)) {
+      padding-bottom: env(safe-area-inset-bottom, 0px);
+    }
+    .cloud-app-canvas[data-layout-authenticated] .layout-content-main .k2b-app-workspace:not(.k2b-app-workspace *) {
+      --k2b-workspace-radius: 0px;
+      --k2b-workspace-inset-bottom: env(safe-area-inset-bottom, 0px);
+      border: 0;
+      box-shadow: none;
+    }
+    .cloud-app-canvas[data-layout-authenticated] > .layout-shell-content > :not(.layout-content-main) .k2b-notice-card {
+      border: 0;
+      border-radius: 0;
+    }
+  }
+}
+
+/* Signed-in card: from 1024 px the app area is a card on the app canvas beside
+   the rail, as on laptops. Its spacing and radius grow with the window, from
+   4 to 8 px and from 10 to 14 px at 1440 px, the wide card from there on, in
+   whole pixels, so the card and its columns keep whole widths. The
+   rail starts at the window's left edge and moves down with the card. In the
+   installed app the card and the rail stay below the status bar; the card keeps
+   its spacing at the bottom, and its surfaces keep their content above the
+   home indicator, as in the flush range. */
+@media (min-width: 1024px) {
   .cloud-app-canvas[data-layout-authenticated] {
-    padding: 0;
+    --cloud-card-inset: round(clamp(0.25rem, calc(0.25rem + (100vw - 64rem) / 104), 0.5rem), 1px);
+    --cloud-card-radius: round(clamp(0.625rem, calc(0.625rem + (100vw - 64rem) / 104), 0.875rem), 1px);
+    --cloud-card-inset-bottom: max(0px, env(safe-area-inset-bottom, 0px) - var(--cloud-card-inset));
+    padding: max(var(--cloud-card-inset), env(safe-area-inset-top, 0px)) max(var(--cloud-card-inset), env(safe-area-inset-right, 0px))
+      var(--cloud-card-inset) 0;
   }
   .cloud-app-canvas[data-layout-authenticated] > .layout-rail {
-    width: calc(3rem + env(safe-area-inset-left, 0px));
-    margin-inline-start: 0;
-    padding: env(safe-area-inset-top, 0px) 0 calc(var(--ui-space-shell) + env(safe-area-inset-bottom, 0px))
-      env(safe-area-inset-left, 0px);
+    padding-bottom: var(--cloud-card-inset-bottom);
   }
   .cloud-app-canvas[data-layout-authenticated] > .layout-shell-content {
-    gap: 0;
-    padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px) 0 0;
-    background: var(--k2b-surface);
+    gap: var(--cloud-card-inset);
   }
-  /* A regular page scrolls `main`, so its end clears the home indicator. A
-     workspace reaches the bottom edge and clears it inside its own surfaces. */
   .cloud-app-canvas[data-layout-authenticated] .layout-content-main:not(:has(.k2b-app-workspace)) {
-    padding-bottom: env(safe-area-inset-bottom, 0px);
+    padding-bottom: var(--cloud-card-inset-bottom);
   }
   .cloud-app-canvas[data-layout-authenticated] .layout-content-main .k2b-app-workspace:not(.k2b-app-workspace *) {
-    --k2b-workspace-radius: 0px;
-    --k2b-workspace-inset-bottom: env(safe-area-inset-bottom, 0px);
-    border: 0;
-    box-shadow: none;
+    --k2b-workspace-radius: var(--cloud-card-radius);
+    --k2b-workspace-inset-bottom: var(--cloud-card-inset-bottom);
+  }
+}
+
+/* Focus: the app bar and the outermost workspace's navigation hide together
+   (Cmd/Ctrl+\ or the sidebar buttons). The canvas carries the state from the
+   `cloud_shell_focus` cookie, so the server renders the same first frame.
+   Phones ignore it. The app area takes the app bar's place and starts at the
+   card spacing, or at the window's edge where it is flush. The button that
+   shows them again floats at the app area's bottom start corner; on touch
+   screens a drag from the 18 px strip at the left edge does the same. From
+   768 to 1023 px the navigation is already an overlay behind the
+   workspace head's button, so there only the app bar hides. */
+.cloud-shell-show,
+.cloud-shell-reveal {
+  display: none;
+}
+
+@media (min-width: 768px) {
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] > .layout-rail {
+    display: none;
+  }
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] .cloud-shell-show {
+    position: absolute;
+    left: calc(env(safe-area-inset-left, 0px) + 0.75rem);
+    bottom: calc(env(safe-area-inset-bottom, 0px) + 0.75rem);
+    z-index: 15;
+    display: flex;
+  }
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] .cloud-shell-show .k2b-icon-button {
+    box-shadow: var(--k2b-shadow-float);
+  }
+}
+
+@media (min-width: 768px) and (pointer: coarse) {
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] > .cloud-shell-reveal {
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 16;
+    display: block;
+    width: calc(1.125rem + env(safe-area-inset-left, 0px));
+    touch-action: pan-y;
+  }
+}
+
+@media (min-width: 768px) {
+  @media not all and (min-width: 1024px) {
+    .cloud-app-canvas[data-layout-authenticated][data-shell-focus] > .layout-shell-content {
+      padding-left: env(safe-area-inset-left, 0px);
+    }
+  }
+}
+
+@media (min-width: 1024px) {
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] {
+    padding-left: max(var(--cloud-card-inset), env(safe-area-inset-left, 0px));
+  }
+  .cloud-app-canvas[data-layout-authenticated][data-shell-focus] .cloud-shell-show {
+    left: calc(max(var(--cloud-card-inset), env(safe-area-inset-left, 0px)) + 0.75rem);
+    bottom: calc(var(--cloud-card-inset) + var(--cloud-card-inset-bottom) + 0.75rem);
+  }
+  /* The navigation leaves like a hidden sidebar: its track, its resize
+     handle, and navigation panes go, and the work area rounds its start
+     corners with the card. An island may wrap the sidebar or Main, as in
+     Grids. */
+  .cloud-app-canvas[data-shell-focus] .k2b-app-workspace:not(.k2b-app-workspace *) {
+    --k2b-workspace-start-radius: var(--k2b-workspace-inner-radius);
   }
-  .cloud-app-canvas[data-layout-authenticated] > .layout-shell-content > :not(.layout-content-main) .k2b-notice-card {
-    border: 0;
-    border-radius: 0;
+  .cloud-app-canvas[data-shell-focus]
+    .k2b-app-workspace:not(.k2b-app-workspace *)
+    > :is(.k2b-app-workspace__sidebar, .k2b-app-workspace__resize[data-app-workspace-resize="sidebar"]),
+  .cloud-app-canvas[data-shell-focus]
+    .k2b-app-workspace:not(.k2b-app-workspace *)
+    > :is(solid-island, solid-client)
+    > :is(.k2b-app-workspace__sidebar, .k2b-app-workspace__resize[data-app-workspace-resize="sidebar"]),
+  .cloud-app-canvas[data-shell-focus]
+    .k2b-app-workspace:not(.k2b-app-workspace *)
+    > .k2b-app-workspace__content
+    > .k2b-app-workspace__main
+    > :is(
+      .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary),
+      .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary) + .k2b-app-workspace__resize,
+      .k2b-app-workspace__resize:has(+ .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary))
+    ),
+  .cloud-app-canvas[data-shell-focus]
+    .k2b-app-workspace:not(.k2b-app-workspace *)
+    > .k2b-app-workspace__content
+    > :is(solid-island, solid-client)
+    > .k2b-app-workspace__main
+    > :is(
+      .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary),
+      .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary) + .k2b-app-workspace__resize,
+      .k2b-app-workspace__resize:has(+ .k2b-app-workspace__main-pane[data-surface="navigation"]:not(.is-primary))
+    ) {
+    display: none;
   }
 }
 

package/src/styles/resource-search.css

@@ -428,6 +428,31 @@
   }
 }
 
+/* On a phone the resource picker is a full-screen sheet: the whole width, from
+   below the status bar to the bottom edge, rounded at the top. Its results
+   take the room the search field and footer leave. Global search keeps its
+   floating card. */
+@media (max-width: 47.999rem) {
+  .cloud-search-dialog.cloud-search-dialog--picker {
+    --search-top: max(0.5rem, env(safe-area-inset-top, 0px));
+    --search-max-height: calc(100dvh - var(--search-top));
+    inset: var(--search-top) 0 auto;
+    transform: none;
+    width: 100%;
+    height: var(--search-max-height);
+    border-width: 1px 0 0;
+    border-radius: var(--ui-radius-frame) var(--ui-radius-frame) 0 0;
+  }
+  .cloud-search-dialog--picker > .cloud-search-dialog__content,
+  .cloud-search-dialog--picker .cloud-resource-search {
+    height: 100%;
+  }
+  .cloud-search-dialog--picker .cloud-resource-search {
+    --search-body-height: max(0px, calc(var(--search-max-height) - 12rem));
+    padding-bottom: max(0.5rem, env(safe-area-inset-bottom, 0px));
+  }
+}
+
 /* Border grips belong only to desktop Spotlight, never the resource picker. */
 .cloud-search-dialog:has(.cloud-global-search) {
   overflow: visible;

package/src/styles/utilities-navigation.css

@@ -750,10 +750,12 @@
   @apply text-[0.6875rem] font-medium normal-case tracking-normal mb-5 text-dimmed select-none;
 }
 
+/* A rail control: a 44 px target in the 56 px rail. Its icon is 20 px
+   (`text-xl` on the icon). */
 @utility rail-item {
   border-right: 0;
   border-radius: var(--ui-radius-surface);
-  @apply w-8 h-8;
+  @apply w-11 h-11;
   @apply flex items-center justify-center text-dimmed;
   @apply transition-[background-color,color] duration-150 ease-out;
 
@@ -795,6 +797,12 @@
   pointer-events: none;
 }
 
+/* On the corner of the rail icon, not of its 44 px target. */
+.rail-item > .cloud-app-badge {
+  top: 0.25rem;
+  right: 0.1875rem;
+}
+
 .app-icon > .cloud-app-badge {
   top: -0.375rem;
   right: -0.375rem;
@@ -841,8 +849,8 @@
 .layout-profile-preferences__link,
 .layout-profile-preferences__dropdown-trigger {
   display: none;
-  width: 2rem;
-  height: 2rem;
+  width: 2.75rem;
+  height: 2.75rem;
   align-items: center;
   justify-content: center;
   padding: 0;

package/src/workflows/store/events.ts

@@ -10,11 +10,28 @@
  * A schedule tick is an event. A button press is an event. An inbound message
  * is an event. Nothing needs its own registration path.
  */
+import { Buffer } from "node:buffer";
 import { type SQL, sql } from "bun";
 import type { WorkflowJsonValue } from "../contracts";
 import { createWorkflowRun } from "./runs";
 import { withTransaction } from "./transaction";
 
+/** UTF-8 bytes of serialized JSON, independently for data and context. */
+export const WORKFLOW_EVENT_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
+
+export class WorkflowEventTooLargeError extends Error {
+  readonly code = "WORKFLOW_EVENT_TOO_LARGE";
+  readonly limitBytes = WORKFLOW_EVENT_MAX_PAYLOAD_BYTES;
+
+  constructor(
+    readonly field: "data" | "context",
+    readonly bytes: number,
+  ) {
+    super(`Workflow event ${field} is ${bytes} bytes; the limit is ${WORKFLOW_EVENT_MAX_PAYLOAD_BYTES} bytes (16 MiB).`);
+    this.name = "WorkflowEventTooLargeError";
+  }
+}
+
 export type WorkflowEventInput = {
   appId: string;
   scopeId: string;
@@ -173,6 +190,13 @@ export const emitWorkflowEvent = async (
   const context = event.context ?? {};
   const authorization = event.authorization ?? {};
 
+  // Validate before even opening a savepoint: callers may catch this inside
+  // their own transaction and continue writing domain state.
+  for (const field of ["data", "context"] as const) {
+    const bytes = Buffer.byteLength(JSON.stringify(field === "data" ? data : context), "utf8");
+    if (bytes > WORKFLOW_EVENT_MAX_PAYLOAD_BYTES) throw new WorkflowEventTooLargeError(field, bytes);
+  }
+
   return withTransaction(options.db, async (tx) => {
     const inserted = await tx<{ id: string }[]>`
       INSERT INTO workflows.event (

package/src/workflows/store/index.ts

@@ -45,8 +45,10 @@ export {
   emitWorkflowEvent,
   listUndispatchedWorkflowEvents,
   type UndispatchedWorkflowEvent,
+  WORKFLOW_EVENT_MAX_PAYLOAD_BYTES,
   type WorkflowEmission,
   type WorkflowEventInput,
+  WorkflowEventTooLargeError,
 } from "./events";
 export {
   getWorkflowRun,
@@ -66,6 +68,12 @@ export {
   type WorkflowStepSummary,
   workflowHealth,
 } from "./observability";
+export {
+  expireWorkflowEventPayloads,
+  expireWorkflowEventPayloadsBatch,
+  startWorkflowEventRetention,
+  WORKFLOW_EVENT_RETENTION_DAYS,
+} from "./retention";
 export {
   beginWorkflowEffect,
   claimWorkflowRun,

package/src/workflows/store/observability.ts

@@ -387,6 +387,7 @@ export type WorkflowRunDetail = WorkflowRunSummary & {
   source: string;
   eventId: string | null;
   eventData: Record<string, WorkflowJsonValue> | null;
+  eventPayloadExpired: boolean;
   steps: WorkflowStepSummary[];
   children: Record<WorkflowRunState, number>;
 };
@@ -412,10 +413,13 @@ export const getWorkflowRun = async (runId: string, options: { db?: SQL } = {}):
       source: string;
       event_id: string | null;
       event_data: Record<string, WorkflowJsonValue> | null;
+      event_payload_expired: boolean;
     })[]
   >`
     SELECT ${db.unsafe(RUN_SELECT)},
-           r.inputs, r.result, r.effects_used, v.effect_budget, v.source, r.event_id, e.data AS event_data
+           r.inputs, r.result, r.effects_used, v.effect_budget, v.source, r.event_id,
+           CASE WHEN e.payload_expired_at IS NULL THEN e.data END AS event_data,
+           (e.payload_expired_at IS NOT NULL) AS event_payload_expired
     ${db.unsafe(RUN_FROM)}
     WHERE r.id = ${runId}::uuid
   `;
@@ -438,6 +442,7 @@ export const getWorkflowRun = async (runId: string, options: { db?: SQL } = {}):
     source: row.source,
     eventId: row.event_id,
     eventData: row.event_data,
+    eventPayloadExpired: row.event_payload_expired,
     children,
     steps,
   };

package/src/workflows/store/retention.ts

@@ -0,0 +1,157 @@
+import { type SQL, sql } from "bun";
+import { logger } from "../../services/logging";
+import { toPgUuidArray } from "../../services/postgres";
+import { withTransaction } from "./transaction";
+
+/**
+ * Events are cause records; runs keep their own inputs and context. After 30
+ * days only the slim cause row remains: Mail backfill and Grids idempotency
+ * still need its dedupe key. This window is fixed, not configurable.
+ */
+export const WORKFLOW_EVENT_RETENTION_DAYS = 30;
+
+const DEFAULT_BATCH_SIZE = 1000;
+const log = logger("workflows:retention");
+
+const retentionIndexes = [
+  {
+    name: "idx_workflows_event_retention",
+    table: "workflows.event",
+    definition:
+      "((COALESCE(dispatched_at, dispatch_failed_at)), id) WHERE payload_expired_at IS NULL AND (dispatched_at IS NOT NULL OR dispatch_failed_at IS NOT NULL)",
+  },
+  {
+    name: "idx_workflows_run_event",
+    table: "workflows.run",
+    definition: "(event_id) WHERE event_id IS NOT NULL",
+  },
+] as const;
+
+const readRetentionIndex = async (db: SQL, index: (typeof retentionIndexes)[number]) => {
+  const name = `workflows.${index.name}`;
+  const [state] = await db<{ present: boolean; valid: boolean; building: boolean }[]>`
+    SELECT to_regclass(${name}) IS NOT NULL AS present,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_index WHERE indexrelid = to_regclass(${name}) AND indisvalid AND indisready AND indislive) AS valid,
+      EXISTS (SELECT 1 FROM pg_catalog.pg_stat_progress_create_index progress
+        WHERE progress.datname = pg_catalog.current_database()
+          AND (progress.relid = to_regclass(${index.table}) OR progress.relid IS NULL)) AS building
+  `;
+  return state ?? { present: false, valid: false, building: false };
+};
+
+const dropRetentionIndex = (db: SQL, name: string) => db.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS workflows.${name}`).simple();
+
+/**
+ * Build after Core setup without blocking event or run writes. Each statement
+ * runs outside a transaction, including through transaction poolers. Interrupted
+ * builds are replaced; active builds are left for the next sweep. Never throws.
+ */
+export const ensureWorkflowEventRetentionIndexes = async (db: SQL = sql): Promise<boolean> => {
+  try {
+    for (const index of retentionIndexes) {
+      const before = await readRetentionIndex(db, index);
+      if (before.valid) continue;
+      if (before.building) return false;
+      if (before.present) await dropRetentionIndex(db, index.name);
+      try {
+        await db.unsafe(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${index.name} ON ${index.table} ${index.definition}`).simple();
+      } catch (error) {
+        const after = await readRetentionIndex(db, index);
+        log.warn("Workflow event retention index build failed; retrying on the next sweep", {
+          index: index.name,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        if (after.present && !after.valid && !after.building) await dropRetentionIndex(db, index.name);
+        return false;
+      }
+      if (!(await readRetentionIndex(db, index)).valid) return false;
+    }
+    return true;
+  } catch (error) {
+    log.warn("Workflow event retention indexes are unavailable; retrying on the next sweep", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+};
+
+/** Expire one bounded batch atomically; concurrent Core replicas skip locked rows. */
+export const expireWorkflowEventPayloadsBatch = async (options: { olderThan: Date; limit?: number; db?: SQL }): Promise<number> => {
+  const limit = options.limit ?? DEFAULT_BATCH_SIZE;
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError("Workflow event retention batch size must be a positive integer.");
+  return withTransaction(options.db, async (tx) => {
+    const rows = await tx<{ id: string }[]>`
+      SELECT e.id FROM workflows.event e
+      WHERE e.payload_expired_at IS NULL
+        AND (e.dispatched_at IS NOT NULL OR e.dispatch_failed_at IS NOT NULL)
+        AND COALESCE(e.dispatched_at, e.dispatch_failed_at) < ${options.olderThan}
+        AND NOT EXISTS (
+          SELECT 1 FROM workflows.run r
+          WHERE r.event_id = e.id AND r.state NOT IN ('succeeded', 'failed', 'canceled')
+        )
+      ORDER BY COALESCE(e.dispatched_at, e.dispatch_failed_at), e.id
+      LIMIT ${limit}
+      FOR UPDATE SKIP LOCKED
+    `;
+    if (rows.length === 0) return 0;
+    const ids = toPgUuidArray(rows.map((row) => row.id));
+    await tx`DELETE FROM workflows.event_delivery WHERE event_id = ANY(${ids}::uuid[])`;
+    await tx`
+      UPDATE workflows.event
+      SET data = '{}'::jsonb, context = '{}'::jsonb, authorization_snapshot = '{}'::jsonb,
+          payload_expired_at = now()
+      WHERE id = ANY(${ids}::uuid[])
+    `;
+    return rows.length;
+  });
+};
+
+/** Sweep for at most five minutes, stopping between batches on cancellation. */
+export const expireWorkflowEventPayloads = async (
+  options: { now?: Date; signal?: AbortSignal; db?: SQL; batchSize?: number } = {},
+): Promise<number> => {
+  const olderThan = new Date((options.now ?? new Date()).getTime() - WORKFLOW_EVENT_RETENTION_DAYS * 86_400_000);
+  const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+  const deadline = Date.now() + 5 * 60_000;
+  let expired = 0;
+  while (!options.signal?.aborted && Date.now() < deadline) {
+    const count = await expireWorkflowEventPayloadsBatch({ olderThan, limit: batchSize, db: options.db });
+    expired += count;
+    if (count < batchSize) break;
+  }
+  return expired;
+};
+
+const RETENTION_INTERVAL_MS = 6 * 60 * 60 * 1000;
+let retentionTimer: ReturnType<typeof setInterval> | null = null;
+let retentionRunning = false;
+
+/** Core owns this scheduler; SKIP LOCKED makes multiple replicas safe. */
+export const startWorkflowEventRetention = (): (() => void) => {
+  if (retentionTimer) return () => undefined;
+  const abort = new AbortController();
+  const expire = async (): Promise<void> => {
+    if (retentionRunning) return;
+    retentionRunning = true;
+    try {
+      if (!(await ensureWorkflowEventRetentionIndexes())) {
+        log.info("Skipped workflow event retention sweep until its indexes are valid");
+        return;
+      }
+      const expired = await expireWorkflowEventPayloads({ signal: abort.signal });
+      if (expired > 0) log.info("Expired workflow event payloads", { expired });
+    } catch (error) {
+      log.error("Workflow event retention sweep failed", { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      retentionRunning = false;
+    }
+  };
+  void expire();
+  retentionTimer = setInterval(() => void expire(), RETENTION_INTERVAL_MS);
+  retentionTimer.unref?.();
+  return () => {
+    abort.abort();
+    if (retentionTimer) clearInterval(retentionTimer);
+    retentionTimer = null;
+  };
+};