@cosmicdrift/kumiko-samples 0.338.0 → 0.340.0

package/packages/bundled-features/src/renderer-simple/feature.ts

@@ -1,4 +1,5 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { NotificationRenderer } from "../delivery/index.js";
 import {
   RENDERER_EXTENSION,
   type RendererContext,
@@ -7,7 +8,7 @@ import {
   type RenderResponse,
 } from "../renderer-foundation/index.js";
 import { resolveNotificationVariables } from "./resolve-variables.js";
-import { simpleRenderer } from "./simple-renderer.js";
+import { createSimpleRenderer, type MailBranding, simpleRenderer } from "./simple-renderer.js";
 
 // Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
 // NotificationRenderer-Contract), renderer-foundation erwartet
@@ -19,6 +20,7 @@ import { simpleRenderer } from "./simple-renderer.js";
 export async function adaptToFoundation(
   req: RenderRequest,
   ctx: RendererContext,
+  renderer: NotificationRenderer = simpleRenderer,
 ): Promise<RenderResponse> {
   if (req.kind !== "notification") {
     // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
@@ -29,14 +31,22 @@ export async function adaptToFoundation(
     );
   }
   const variables = await resolveNotificationVariables(req, ctx);
-  const html = await simpleRenderer.render({
+  const html = await renderer.render({
     template: req.payload.template ?? "",
     variables,
   });
   return { kind: "notification", html };
 }
 
-export function createRendererSimpleFeature(): FeatureDefinition {
+export type RendererSimpleOptions = {
+  /** Branding applied to every notification mail, including the framework auth mails. */
+  readonly mailBranding?: MailBranding;
+};
+
+export function createRendererSimpleFeature(options?: RendererSimpleOptions): FeatureDefinition {
+  const renderer = options?.mailBranding
+    ? createSimpleRenderer(options.mailBranding)
+    : simpleRenderer;
   return defineFeature("renderer-simple", (r) => {
     r.describe(
       'Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.',
@@ -51,7 +61,7 @@ export function createRendererSimpleFeature(): FeatureDefinition {
 
     r.useExtension(RENDERER_EXTENSION, "simple", {
       kinds: ["notification"] as const,
-      render: adaptToFoundation,
+      render: (req, ctx) => adaptToFoundation(req, ctx, renderer),
     });
   });
 }

package/packages/bundled-features/src/renderer-simple/index.ts

@@ -1,2 +1,2 @@
-export { createRendererSimpleFeature } from "./feature.js";
-export { simpleRenderer } from "./simple-renderer.js";
+export { createRendererSimpleFeature, type RendererSimpleOptions } from "./feature.js";
+export { createSimpleRenderer, type MailBranding, simpleRenderer } from "./simple-renderer.js";

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -1,6 +1,62 @@
-import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { NotificationRenderer } from "../delivery/index.js";
 
+export type MailBranding = {
+  /** Shown as text when there is no logo, and as the logo alt text. */
+  readonly productName?: string;
+  /** Hex color (#rgb, #rrggbb, #rrggbbaa); used for buttons and the header accent. */
+  readonly primaryColor?: string;
+  /** Absolute http(s) URL; anything else is dropped. */
+  readonly logoUrl?: string;
+  readonly footerText?: string;
+  /** Absolute http(s) URLs only; other entries are dropped. */
+  readonly footerLinks?: readonly { readonly label: string; readonly url: string }[];
+};
+
+const DEFAULT_PRIMARY_COLOR = "#2563eb";
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function resolvePrimaryColor(branding: MailBranding | undefined): string {
+  const color = branding?.primaryColor;
+  return color && HEX_COLOR_PATTERN.test(color) ? color : DEFAULT_PRIMARY_COLOR;
+}
+
+function renderBrandingHeader(branding: MailBranding | undefined, primaryColor: string): string {
+  if (!branding) return "";
+  const logoUrl = branding.logoUrl && isHttpUrl(branding.logoUrl) ? branding.logoUrl : undefined;
+  if (!logoUrl && !branding.productName) return "";
+  const logo = logoUrl
+    ? `<img src="${escapeHtmlAttr(logoUrl)}" alt="${escapeHtmlAttr(branding.productName ?? "")}" style="display:block;max-height:40px;max-width:200px;border:0" />`
+    : `<span style="font-size:18px;font-weight:700;color:${escapeHtmlAttr(primaryColor)}">${escapeHtml(branding.productName ?? "")}</span>`;
+  return `<div style="margin:0 0 24px;padding:0 0 16px;border-bottom:3px solid ${escapeHtmlAttr(primaryColor)}">${logo}</div>`;
+}
+
+function renderBrandingFooter(branding: MailBranding | undefined): string {
+  if (!branding) return "";
+  const links = (branding.footerLinks ?? [])
+    .filter((link) => isHttpUrl(link.url))
+    .map(
+      (link) =>
+        `<a href="${escapeHtmlAttr(link.url)}" style="color:#999">${escapeHtml(link.label)}</a>`,
+    );
+  const footerPartsHtml = [
+    branding.footerText ? escapeHtml(branding.footerText) : "",
+    links.join(" · "),
+  ].filter((part) => part !== "");
+  if (footerPartsHtml.length === 0) return "";
+  const footerHtml = footerPartsHtml.join("<br />");
+  return `<p style="margin:16px 0 0;color:#999;font-size:12px">${footerHtml}</p>`;
+}
+
 type Section =
   | { readonly text: string }
   | { readonly button: { readonly label: string; readonly url: string } };
@@ -15,51 +71,58 @@ type EmailTemplateData = {
   readonly body?: string;
 };
 
-function renderSection(section: Section): string {
+function renderSection(section: Section, primaryColor: string): string {
   if ("text" in section) {
     return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
   }
   if ("button" in section) {
-    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
+    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
   }
   return "";
 }
 
 // Simple Renderer: turns structured email template data into HTML with inline CSS.
 // No external dependencies, no template engine — just string concatenation.
-export const simpleRenderer: NotificationRenderer = {
-  name: "simple",
+export function createSimpleRenderer(branding?: MailBranding): NotificationRenderer {
+  const primaryColor = resolvePrimaryColor(branding);
+  return {
+    name: "simple",
+
+    async render(input) {
+      const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
 
-  async render(input) {
-    const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
+      // Fallback: if no structured fields, use title + body as header + single text section
+      const header = data.header ?? data.title;
+      const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
 
-    // Fallback: if no structured fields, use title + body as header + single text section
-    const header = data.header ?? data.title;
-    const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+      const parts: string[] = [];
+      parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
+      parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+      parts.push(renderBrandingHeader(branding, primaryColor));
 
-    const parts: string[] = [];
-    parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
-    parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+      if (header) {
+        parts.push(
+          `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
+        );
+      }
 
-    if (header) {
-      parts.push(
-        `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
-      );
-    }
+      if (sections) {
+        for (const section of sections) {
+          parts.push(renderSection(section, primaryColor));
+        }
+      }
 
-    if (sections) {
-      for (const section of sections) {
-        parts.push(renderSection(section));
+      if (data.footer) {
+        parts.push(
+          `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
+        );
       }
-    }
 
-    if (data.footer) {
-      parts.push(
-        `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
-      );
-    }
+      parts.push(renderBrandingFooter(branding));
+      parts.push("</div></body></html>");
+      return parts.join("");
+    },
+  };
+}
 
-    parts.push("</div></body></html>");
-    return parts.join("");
-  },
-};
+export const simpleRenderer: NotificationRenderer = createSimpleRenderer();

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

@@ -183,7 +183,7 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
         rotateJob(
           payload,
           ctx,
-          ctx.db.unsafeRaw(ROTATE_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
         ),
     });
 

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

@@ -177,7 +177,7 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
           cleanupJob(
             payload,
             ctx,
-            ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+            ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           ),
       });
 

package/packages/bundled-features/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -49,7 +49,7 @@ export const revokeAllForUserWrite = defineWriteHandler({
     reason: REVOKE_ALL_SESSIONS_REASON,
   },
   handler: async (event, ctx) => {
-    const runner = ctx.db.unsafeRaw(REVOKE_ALL_SESSIONS_REASON);
+    const runner = ctx.db.unsafeRaw();
     const updated = await updateMany<{ id: string }>(
       runner,
       userSessionTable,

package/packages/bundled-features/src/tenant-handover/handlers/claim.write.ts

@@ -51,10 +51,7 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
     agent: { expose: false },
     rateLimit: { per: "user", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      const db = ctx.db.unsafeRaw(
-        "tenant-handover claim: cross-tenant read + ownership write, legitimized by the " +
-          "row-bound grant redeemed below",
-      );
+      const db = ctx.db.unsafeRaw();
       const rootLocation = resolveRootAnchorLocation(ctx.registry, db, event.payload.entityType);
       if (!rootLocation) return notTransferable(event.payload.entityType);
       const { rootTableName, rootIdCol, rootTenantCol, loadAnchor } = rootLocation;

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -126,9 +126,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
         await runTenantDestructionSweep({
-          db: ctx.db.unsafeRaw(
-            RUN_TENANT_DESTRUCTION_REASON,
-          ) as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          db: ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           registry: ctx.registry,
           now: T.Now.instant(),
           log: (message) => ctx.log?.warn(message),

package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -30,11 +30,9 @@ export const cancelDestructionWrite = defineWriteHandler({
   },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
-    const row = await fetchOne<TenantLifecycleRow>(
-      ctx.db.unsafeRaw(CANCEL_DESTRUCTION_TENANT_ROW_REASON),
-      tenantTable,
-      { id: tenantId },
-    );
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.unsafeRaw(), tenantTable, {
+      id: tenantId,
+    });
     if (!row) {
       return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
     }

package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -34,7 +34,7 @@ export const requestDestructionWrite = defineWriteHandler({
   },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
-    const runner = ctx.db.unsafeRaw(REQUEST_DESTRUCTION_TENANT_ROW_REASON);
+    const runner = ctx.db.unsafeRaw();
     const row = await fetchOne<TenantLifecycleRow>(runner, tenantTable, { id: tenantId });
     if (!row) {
       return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -399,7 +399,7 @@ export function createTierEngineFeature<
           const rawDb = ctx.systemDb
             ? ctx.systemDb.unsafeRaw(autoDefaultTierHookReason)
             : ctx.db && "unsafeRaw" in ctx.db
-              ? ctx.db.unsafeRaw(autoDefaultTierHookReason)
+              ? ctx.db.unsafeRaw()
               : undefined;
           // skip: defensive — inTransaction phase always sets db, but AppContext's
           // type makes it optional. Throwing would be overreach (lifecycle

package/packages/bundled-features/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -25,7 +25,7 @@ export const getTenantTierQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const tenantId = query.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-    const tdb = createTenantDb(ctx.db.unsafeRaw(GET_TENANT_TIER_REASON), tenantId, "system");
+    const tdb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
     const row = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
     return row ?? null;
   },

package/packages/bundled-features/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -73,7 +73,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
     },
     handler: async (event, ctx) => {
       const tenantId = event.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-      const rawDb = ctx.db.unsafeRaw(SET_TENANT_TIER_REASON);
+      const rawDb = ctx.db.unsafeRaw();
       const tdb = createTenantDb(rawDb, tenantId, "system");
       const systemUser = { ...event.user, tenantId };
       const tier = event.payload.tier;

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "The last-SystemAdmin check uses jsonb containment through selectMany",
+    "detail": "Removing the SystemAdmin role still refuses to drop the last active SystemAdmin; the count now comes from `selectMany` with a roles containment filter instead of raw SQL.",
+    "migration": "keine"
+  },
   {
     "version": "0.271.0",
     "type": "improvement",
@@ -8,7 +15,7 @@
   {
     "version": "0.218.1",
     "type": "improvement",
-    "title": "user.email searchable \u2014 reindex required after upgrade",
+    "title": "user.email searchable — reindex required after upgrade",
     "detail": "email gained searchable for roster lookup. buildSearchDocument only runs on write; existing rows need reindexEntity(\"user\") (or the reindex job) plus Meili configure for the new attribute.",
     "migration": "After deploying, run reindexEntity(\"user\") (or the existing reindex job) so pre-upgrade user rows appear in roster search."
   },
@@ -16,28 +23,28 @@
     "version": "0.218.0",
     "type": "fix",
     "title": "user-list: system-scope search; membership roles on tenants; emailVerified sort",
-    "detail": "systemScope entityList search uses SYSTEM_TENANT_ID (was session tenant \u2192 Meili miss/500). Tenants column shows membership roles (Offlot Demo (TenantAdmin)). emailVerified sortable; email also searchable for roster lookup. Global roles stay SystemAdmin-only \u2014 TenantAdmin/Admin live on membership (Team \u2192 Members)."
+    "detail": "systemScope entityList search uses SYSTEM_TENANT_ID (was session tenant → Meili miss/500). Tenants column shows membership roles (Offlot Demo (TenantAdmin)). emailVerified sortable; email also searchable for roster lookup. Global roles stay SystemAdmin-only — TenantAdmin/Admin live on membership (Team → Members)."
   },
   {
     "version": "0.217.0",
     "type": "improvement",
     "title": "user-list: roles multiSelect + tenants column; roles editable as SystemAdmin (fw#2384 follow-up)",
-    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box \u2014 SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
-    "migration": "Run `kumiko-schema generate` and apply \u2014 migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
+    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box — SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
+    "migration": "Run `kumiko-schema generate` and apply — migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
   },
   {
     "version": "0.167.1",
     "type": "breaking",
     "title": "user.locale no longer defaults to \"de\" (fw#1637).",
     "detail": "The entity-level default contradicted tenant-settings' own \"en\" default and silently overrode any app or tenant locale configuration for every new user. locale now stays unset until the client or a resolution chain provides one. Consumers that already fall back with `user.locale ?? \"en\"` are unaffected in shape but now see null instead of \"de\".",
-    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration emits `ALTER TABLE read_users ALTER COLUMN locale DROP DEFAULT`. Note that DROP DEFAULT only affects future inserts: existing rows keep the \"de\" the old default wrote, which no user ever chose. Your app therefore splits into pre-bump users on \"de\" and post-bump users on null, and each group resolves to a different language. Decide deliberately: either keep the old values (and state that pre-bump users stay German), or run `UPDATE read_users SET locale = NULL WHERE locale = 'de'` once so every user follows the same chain \u2014 the latter only if no UI ever let users edit the field, otherwise it erases real choices. If your app relied on the implicit German default, set an explicit fallback instead (fw#1653)."
+    "migration": "Run `kumiko-schema generate` and apply — the migration emits `ALTER TABLE read_users ALTER COLUMN locale DROP DEFAULT`. Note that DROP DEFAULT only affects future inserts: existing rows keep the \"de\" the old default wrote, which no user ever chose. Your app therefore splits into pre-bump users on \"de\" and post-bump users on null, and each group resolves to a different language. Decide deliberately: either keep the old values (and state that pre-bump users stay German), or run `UPDATE read_users SET locale = NULL WHERE locale = 'de'` once so every user follows the same chain — the latter only if no UI ever let users edit the field, otherwise it erases real choices. If your app relied on the implicit German default, set an explicit fallback instead (fw#1653)."
   },
   {
     "version": "0.167.1",
     "type": "improvement",
     "title": "user.timezone field, wired into ctx.tz (fw#1636).",
     "detail": "The user entity gains a `timezone` field (createTzField, no default). buildHandlerContext passes it to ctx.tz.user; the fallback chain stays tenant.timezone, then \"UTC\". Before this, ctx.tz.tenant and ctx.tz.user both hardcoded \"UTC\" while the plumbing already accepted per-request values.",
-    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration adds `read_users.timezone`. No backfill: an unset timezone falls through to the tenant's, exactly as before the field existed."
+    "migration": "Run `kumiko-schema generate` and apply — the migration adds `read_users.timezone`. No backfill: an unset timezone falls through to the tenant's, exactly as before the field existed."
   },
   {
     "version": "0.165.3",

package/packages/bundled-features/src/user/handlers/update-roles.ts

@@ -1,4 +1,4 @@
-import { asEntityTableMeta, asRawClient, fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   acquireNamespacedAdvisoryLock,
   createEventStoreExecutor,
@@ -40,10 +40,6 @@ type UserRolesRow = {
   isDeleted?: boolean;
 };
 
-function quoteIdent(name: string): string {
-  return `"${name.replace(/"/g, '""')}"`;
-}
-
 function isActiveUserRow(row: UserRolesRow): boolean {
   if (row.isDeleted === true) return false;
   return row.status === USER_STATUS.Active || !row.status;
@@ -54,21 +50,11 @@ function isActiveSystemAdminRow(row: UserRolesRow): boolean {
 }
 
 async function countOtherActiveSystemAdmins(db: DbRunner, excludeUserId: string): Promise<number> {
-  const tableName = asEntityTableMeta(userTable)?.tableName;
-  if (!tableName) {
-    throw new InternalError({ message: "user read table meta missing" });
-  }
-  // kumiko-lint-ignore raw-sql jsonb @> prefilter for SystemAdmin roster under advisory lock
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT id, roles, status, is_deleted AS "isDeleted"
-     FROM ${quoteIdent(tableName)}
-     WHERE is_deleted = false
-       AND (status = $1 OR status IS NULL)
-       AND roles @> $2::jsonb`,
-    // Pass a JS array — JSON.stringify + $n::jsonb double-encodes to a jsonb string
-    // (postgres.js), so `@>` never matches a roles array.
-    [USER_STATUS.Active, ["SystemAdmin"]],
-  )) as UserRolesRow[];
+  // `roles` is a jsonb multiSelect column: a scalar filter value means `@>` containment.
+  const rows = await selectMany<UserRolesRow>(db, userTable, {
+    isDeleted: false,
+    roles: "SystemAdmin",
+  });
   return rows.filter((u) => u.id !== excludeUserId && isActiveSystemAdminRow(u)).length;
 }
 
@@ -138,9 +124,7 @@ export async function applyUserRolesUpdate(
     // observe otherActiveSystemAdmins >= 1 and leave zero active SystemAdmins.
     await acquireNamespacedAdvisoryLock(lockRunner, LAST_SYSTEM_ADMIN_LOCK_NAMESPACE, "global");
     const otherActiveSystemAdmins = await countOtherActiveSystemAdmins(
-      ctx.systemDb.unsafeRaw(
-        "jsonb @> prefilter over the global users table to count remaining active SystemAdmins",
-      ),
+      ctx.systemDb.unsafeRaw("count remaining active SystemAdmins across the global users table"),
       event.payload.id,
     );
     if (otherActiveSystemAdmins === 0) {

package/packages/bundled-features/src/user-data-rights/feature.ts

@@ -588,9 +588,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         // Discriminator wird via handlerName="user-data-rights:run-export-
         // jobs" im Secret-Read-Audit erfasst.
         const exportUserId = ctx._userId ?? SYSTEM_USER_ID;
-        const exportDb = ctx.db.unsafeRaw(
-          RUN_EXPORT_JOBS_REASON,
-        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const exportDb =
+          ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const exportRegistry = ctx.registry;
         // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
         // handle only exists on HandlerContext (built per write/query call
@@ -684,9 +683,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
         const forgetUserId = ctx._userId ?? SYSTEM_USER_ID;
-        const forgetDb = ctx.db.unsafeRaw(
-          RUN_FORGET_CLEANUP_REASON,
-        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const forgetDb =
+          ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const forgetRegistry = ctx.registry;
         const tenantModel = await resolveAppTenantModel({
           registry: forgetRegistry,

package/packages/bundled-features/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -61,7 +61,7 @@ export const cancelDeletionWrite = defineWriteHandler({
       return writeFailure(new UnprocessableError("grace_period_expired"));
     }
 
-    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), event.user.id, {
+    await updateUserLifecycle(ctx.db.unsafeRaw(), event.user.id, {
       status: USER_STATUS.Active,
       gracePeriodEnd: null,
       // #354/1: closes the replay-after-cancel window — a still-TTL-valid email

package/packages/bundled-features/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -83,9 +83,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
             ctx,
             userId,
             () => resolveGracePeriod(ctx, event.user.tenantId),
-            ctx.db.unsafeRaw(
-              "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream",
-            ),
+            ctx.db.unsafeRaw(),
             { pendingDeletionRequestId: requestId },
           );
           if (!res.ok) return false;

package/packages/bundled-features/src/user-data-rights/handlers/download-by-job.query.ts

@@ -87,7 +87,7 @@ export const downloadByJobQuery = defineQueryHandler({
     // Wert (603/2).
     const auditIp = requestContext.get()?.ip ?? null;
     const auditUa = requestContext.get()?.userAgent ?? null;
-    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_JOB_REASON);
+    const runner = ctx.db.unsafeRaw();
 
     // Step 1-2: job-lookup + cross-user-isolation
     const jobRow = await fetchOne<JobRow>(runner, exportJobsTable, { id: jobId });

package/packages/bundled-features/src/user-data-rights/handlers/download-by-token.query.ts

@@ -92,7 +92,7 @@ export const downloadByTokenQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const T = getTemporal();
     const now = T.Now.instant();
-    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_TOKEN_REASON);
+    const runner = ctx.db.unsafeRaw();
 
     // Step 1: hash + lookup
     const hash = await hashDownloadToken(query.payload.token);

package/packages/bundled-features/src/user-data-rights/handlers/export-status.query.ts

@@ -50,7 +50,7 @@ export const exportStatusQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const rows = await selectMany<ExportJobRow>(
-      ctx.db.unsafeRaw(EXPORT_STATUS_REASON),
+      ctx.db.unsafeRaw(),
       exportJobsTable,
       { userId: query.user.id },
       { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },

package/packages/bundled-features/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -7,10 +7,6 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
 
 const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
   "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
-const CHECK_TARGET_MEMBERSHIP_REASON =
-  "checks the target user's membership in the admin's tenant via the DbRunner helper";
-const APPEND_LIFECYCLE_EVENT_REASON =
-  "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
 
 // POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
 //
@@ -46,7 +42,7 @@ export const liftRestrictionWrite = defineWriteHandler({
     const targetUserId = event.payload.userId;
 
     const outside = await denyIfTargetOutsideAdminTenant(
-      ctx.db.unsafeRaw(CHECK_TARGET_MEMBERSHIP_REASON),
+      ctx.db.unsafeRaw(),
       event.user,
       targetUserId,
     );
@@ -73,7 +69,7 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), targetUserId, {
+    await updateUserLifecycle(ctx.db.unsafeRaw(), targetUserId, {
       status: USER_STATUS.Active,
     });
 

package/packages/bundled-features/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -64,7 +64,7 @@ export const myAuditLogQuery = defineQueryHandler({
       type: string;
       payload: Record<string, unknown>;
       created_at: unknown;
-    }>(ctx.db.unsafeRaw(MY_AUDIT_LOG_REASON), eventsTable, where, {
+    }>(ctx.db.unsafeRaw(), eventsTable, where, {
       orderBy: { col: "id", direction: "desc" },
       limit: p.limit,
     });

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -92,7 +92,7 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
       // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
       const requestId = crypto.randomUUID();
-      await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), userRow["id"], {
+      await updateUserLifecycle(ctx.db.unsafeRaw(), userRow["id"], {
         pendingDeletionRequestId: requestId,
       });
 

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion.write.ts

@@ -65,7 +65,7 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
         ctx,
         event.user.id,
         () => resolveGracePeriod(ctx, event.user.tenantId),
-        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
+        ctx.db.unsafeRaw(),
       );
       if (!res.ok) return writeFailure(res.error);
       const { gracePeriodEnd, userEmail, userLocale } = res;

package/packages/bundled-features/src/user-data-rights/handlers/request-export.write.ts

@@ -77,7 +77,7 @@ export const requestExportWrite = defineWriteHandler({
     const userId = event.user.id;
     const T = getTemporal();
     const now = T.Now.instant();
-    const exportJobRunner = ctx.db.unsafeRaw(REQUEST_EXPORT_REASON);
+    const exportJobRunner = ctx.db.unsafeRaw();
 
     // Pre-Check: exportJobRunner bypasses the TenantDb-Filter — the
     // TenantDb-Wrapper would hide cross-tenant jobs.

package/packages/bundled-features/src/user-data-rights/handlers/restrict-account.write.ts

@@ -70,9 +70,7 @@ export const restrictAccountWrite = defineWriteHandler({
         );
       }
       const outside = await denyIfTargetOutsideAdminTenant(
-        ctx.db.unsafeRaw(
-          "checks the target user's membership in the admin's tenant via the DbRunner helper",
-        ),
+        ctx.db.unsafeRaw(),
         event.user,
         targetUserId,
       );
@@ -107,11 +105,7 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(
-      ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
-      targetUserId,
-      { status: USER_STATUS.Restricted },
-    );
+    await updateUserLifecycle(ctx.db.unsafeRaw(), targetUserId, { status: USER_STATUS.Restricted });
 
     // Cross-Feature: alle live sessions revoken — sonst koennte der User
     // mit existierendem JWT bis zur Token-Expiry weiter schreiben.

package/packages/bundled-features/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -48,7 +48,7 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
       }
 
       const T = getTemporal();
-      const runner = ctx.db.unsafeRaw(RUN_FORGET_CLEANUP_REASON);
+      const runner = ctx.db.unsafeRaw();
       // Operator-triggered forget must also erase binaries, not just rows —
       // it flips users to Deleted, after which the cron never re-processes
       // them, so a row-only delete here would permanently leak the binaries.