@cosmicdrift/kumiko-samples 0.339.0 → 0.340.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.339.0",
+  "version": "0.340.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.339.0",
+  "version": "0.340.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/billing-foundation/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Payment and subscription projections use typed bun-db helpers",
+    "detail": "`payment-received` inserts through `insertOnConflictDoNothing`, subscription events upsert through `upsertOnConflict`. The raw `db/queries/payment-projection.ts` and `subscription-projection.ts` modules are gone.",
+    "migration": "keine"
+  },
   {
     "version": "0.339.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/projection.ts

@@ -14,11 +14,14 @@
 // `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
 // import). setupTestStack pusht sie automatisch via r.projection.table.
 
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  insertOnConflictDoNothing,
+  requireEntityTableMeta,
+  upsertOnConflict,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { paymentRowId } from "./aggregate-id.js";
-import { insertPaymentProjectionRow } from "./db/queries/payment-projection.js";
-import { upsertSubscriptionProjectionRow } from "./db/queries/subscription-projection.js";
 import { paymentEntity, subscriptionEntity } from "./entities.js";
 import type { PaymentEventPayload, SubscriptionEventPayload } from "./events.js";
 
@@ -32,6 +35,17 @@ export const subscriptionsProjectionTable = buildEntityTable("subscription", sub
 // production must add read_payments to their own drizzle/generate.ts too.
 export const paymentsProjectionTable = buildEntityTable("payment", paymentEntity);
 
+// Unbranded metas: the apply functions below ARE the executor of these
+// projections, so they may write through the typed helpers.
+const subscriptionsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  subscriptionsProjectionTable,
+  "subscription",
+);
+const paymentsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  paymentsProjectionTable,
+  "payment",
+);
+
 // =============================================================================
 // Shared helpers
 // =============================================================================
@@ -69,9 +83,7 @@ function cancelAtSetFromPayload(p: SubscriptionEventPayload): {
  *  on every apply including the initial create — a projection rebuild at a
  *  different wall-clock time must materialize the exact same row, and
  *  `getSubscriptionForTenant`'s `lastChangedAt` (staleness check for
- *  incomplete subscriptions) depends on that determinism. Raw `.unsafe()`
- *  bypasses the typed query-builder's Temporal.Instant-to-string coercion,
- *  hence the explicit `.toString()`. */
+ *  incomplete subscriptions) depends on that determinism. */
 async function upsert(
   tx: Parameters<Parameters<typeof defineApply<SubscriptionEventPayload>>[0]>[1],
   event: { aggregateId: string; tenantId: string; createdAt: Temporal.Instant },
@@ -92,38 +104,21 @@ async function upsert(
   // INSERT-Pfad und nur den teil-`set` für ON CONFLICT.
   const insertCols = {
     id: event.aggregateId,
-    tenant_id: event.tenantId,
-    provider_name: fullPayload.providerName,
-    provider_customer_id: fullPayload.providerCustomerId,
-    provider_subscription_id: fullPayload.providerSubscriptionId,
+    tenantId: event.tenantId,
+    providerName: fullPayload.providerName,
+    providerCustomerId: fullPayload.providerCustomerId,
+    providerSubscriptionId: fullPayload.providerSubscriptionId,
     status: fullPayload.status,
     tier: fullPayload.tier,
-    current_period_end: fullPayload.currentPeriodEndIso,
-    cancel_at: fullPayload.cancelAtIso ?? null,
-    modified_at: event.createdAt.toString(),
+    currentPeriodEnd: fullPayload.currentPeriodEndIso,
+    cancelAt: fullPayload.cancelAtIso ?? null,
+    modifiedAt: event.createdAt,
   };
-  // Map camelCase set-keys to snake_case DB columns.
-  const setMap: Record<keyof typeof set, string> = {
-    providerName: "provider_name",
-    providerCustomerId: "provider_customer_id",
-    providerSubscriptionId: "provider_subscription_id",
-    status: "status",
-    tier: "tier",
-    currentPeriodEnd: "current_period_end",
-    cancelAt: "cancel_at",
-  };
-  const insertParams = Object.values(insertCols);
-  const setEntries = Object.entries(set).filter(([, v]) => v !== undefined);
-  // modified_at is already bound as the last insertParams placeholder —
-  // reused (not re-pushed) for the ON CONFLICT SET clause below.
-  const setClauses: string[] = [`"modified_at" = $${insertParams.length}`];
-  const allParams: unknown[] = [...insertParams];
-  for (const [k, v] of setEntries) {
-    allParams.push(v);
-    setClauses.push(`"${setMap[k as keyof typeof set]}" = $${allParams.length}`);
-  }
-  const tableName = (subscriptionsProjectionTable as { tableName: string }).tableName;
-  await upsertSubscriptionProjectionRow(tx, tableName, insertCols, setClauses, allParams);
+  const definedSet = Object.fromEntries(Object.entries(set).filter(([, v]) => v !== undefined));
+  await upsertOnConflict(tx, subscriptionsProjectionMeta, insertCols, {
+    conflictKeys: ["id"],
+    update: { modifiedAt: event.createdAt, ...definedSet },
+  });
 }
 
 // =============================================================================
@@ -209,7 +204,6 @@ export const applyInvoicePaymentFailed = defineApply<SubscriptionEventPayload>(
  *  the second tenant's row. ON CONFLICT DO NOTHING also makes a projection
  *  rebuild idempotent without mutating an existing row. */
 export const applyPaymentReceived = defineApply<PaymentEventPayload>(async (event, tx) => {
-  const tableName = (paymentsProjectionTable as { tableName: string }).tableName;
   const providerEventId = event.metadata.headers?.["providerEventId"];
   const providerName = event.metadata.headers?.["providerName"];
   if (typeof providerEventId !== "string" || typeof providerName !== "string") {
@@ -217,11 +211,11 @@ export const applyPaymentReceived = defineApply<PaymentEventPayload>(async (even
       "applyPaymentReceived: event.metadata.headers is missing providerEventId/providerName — process-payment-event.write.ts always sets both",
     );
   }
-  await insertPaymentProjectionRow(tx, tableName, {
+  await insertOnConflictDoNothing(tx, paymentsProjectionMeta, {
     id: paymentRowId(event.tenantId, providerName, providerEventId),
-    tenant_id: event.tenantId,
-    provider_name: event.payload.providerName,
-    provider_customer_id: event.payload.providerCustomerId,
-    price_id: event.payload.priceId,
+    tenantId: event.tenantId,
+    providerName: event.payload.providerName,
+    providerCustomerId: event.payload.providerCustomerId,
+    priceId: event.payload.priceId,
   });
 });

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Inbound mail projections use typed bun-db helpers",
+    "detail": "Mail-account and mail-thread events upsert through `upsertOnConflict` (`connectedAt` is only written on insert), inbound messages insert through `insertOnConflictDoNothing`. The raw `db/queries/inbound-projections.ts` module is gone.",
+    "migration": "keine"
+  },
   {
     "version": "0.339.0",
     "type": "improvement",

package/packages/bundled-features/src/inbound-mail-foundation/projection.ts

@@ -17,12 +17,13 @@
 // write-handler. Die applies kopieren nur durch; decrypted wird erst
 // in den list-queries.
 
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
-import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import {
-  insertIgnoreProjectionRow,
-  upsertProjectionRow,
-} from "./db/queries/inbound-projections.js";
+  insertOnConflictDoNothing,
+  requireEntityTableMeta,
+  upsertOnConflict,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.js";
 import type {
   InboundMessageEventPayload,
@@ -39,9 +40,20 @@ export const inboundMessagesProjectionTable = buildEntityTable(
 );
 export const mailThreadsProjectionTable = buildEntityTable("mail-thread", mailThreadEntity);
 
-function tableNameOf(table: unknown): string {
-  return (table as { tableName: string }).tableName;
-}
+// Unbranded metas: the apply functions below ARE the executor of these
+// projections, so they may write through the typed helpers.
+const mailAccountsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  mailAccountsProjectionTable,
+  "mail-account",
+);
+const inboundMessagesProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  inboundMessagesProjectionTable,
+  "inbound-message",
+);
+const mailThreadsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+  mailThreadsProjectionTable,
+  "mail-thread",
+);
 
 // =============================================================================
 // mail-account — connected/updated/disconnected teilen den payload-shape,
@@ -49,40 +61,30 @@ function tableNameOf(table: unknown): string {
 // defensive consistency (rebuild-aus-dem-Nichts, out-of-order).
 // =============================================================================
 
-const ACCOUNT_SET_CLAUSES = [
-  `"provider" = EXCLUDED."provider"`,
-  `"auth_method" = EXCLUDED."auth_method"`,
-  `"owner_user_id" = EXCLUDED."owner_user_id"`,
-  `"display_name" = EXCLUDED."display_name"`,
-  `"address" = EXCLUDED."address"`,
-  `"status" = EXCLUDED."status"`,
-  `"watch_state" = EXCLUDED."watch_state"`,
-  // connected_at bewusst NICHT im SET: der Erst-Connect-Zeitpunkt
-  // bleibt stehen, updated/disconnected überschreiben ihn nicht.
-];
-
 const applyMailAccountUpsert = defineApply<MailAccountEventPayload>(async (event, tx) => {
   const p = event.payload;
-  const insertCols = {
-    id: event.aggregateId,
-    tenant_id: event.tenantId,
+  const mutable = {
     provider: p.provider,
-    auth_method: p.authMethod,
-    owner_user_id: p.ownerUserId,
-    display_name: p.displayName,
+    authMethod: p.authMethod,
+    ownerUserId: p.ownerUserId,
+    displayName: p.displayName,
     address: p.address,
     status: p.status,
-    watch_state: p.watchState,
-    // Insert-Pfad = Erst-Connect (bzw. Rebuild: createdAt des ersten
-    // events des Streams — fachlich derselbe Zeitpunkt).
-    connected_at: event.createdAt.toString(),
+    watchState: p.watchState,
   };
-  await upsertProjectionRow(
+  await upsertOnConflict(
     tx,
-    tableNameOf(mailAccountsProjectionTable),
-    insertCols,
-    ACCOUNT_SET_CLAUSES,
-    Object.values(insertCols),
+    mailAccountsProjectionMeta,
+    {
+      id: event.aggregateId,
+      tenantId: event.tenantId,
+      ...mutable,
+      // Only the insert path is the first connect (on rebuild: createdAt of the
+      // stream's first event, the same moment). Left out of `update` so the
+      // first-connect time survives updated/disconnected events.
+      connectedAt: event.createdAt,
+    },
+    { conflictKeys: ["id"], update: mutable },
   );
 });
 
@@ -104,20 +106,20 @@ export const applyMailAccountDisconnected = applyMailAccountUpsert;
 export const applyInboundMessageReceived = defineApply<InboundMessageEventPayload>(
   async (event, tx) => {
     const p = event.payload;
-    await insertIgnoreProjectionRow(tx, tableNameOf(inboundMessagesProjectionTable), {
+    await insertOnConflictDoNothing(tx, inboundMessagesProjectionMeta, {
       id: event.aggregateId,
-      tenant_id: event.tenantId,
-      account_id: p.accountId,
-      owner_user_id: p.ownerUserId,
-      message_id_header: p.messageIdHeader,
-      thread_key: p.threadKey,
+      tenantId: event.tenantId,
+      accountId: p.accountId,
+      ownerUserId: p.ownerUserId,
+      messageIdHeader: p.messageIdHeader,
+      threadKey: p.threadKey,
       from: p.from,
       to: p.to,
       cc: p.cc,
       subject: p.subject,
       snippet: p.snippet,
-      received_at: p.receivedAtIso,
-      body_ref: p.bodyRef,
+      receivedAt: p.receivedAtIso,
+      bodyRef: p.bodyRef,
       scope: p.scope,
     });
   },
@@ -133,23 +135,20 @@ export const applyInboundMessageReceived = defineApply<InboundMessageEventPayloa
 /** mail-thread-updated → UPSERT full mit dem Payload-Snapshot. */
 export const applyMailThreadUpdated = defineApply<MailThreadEventPayload>(async (event, tx) => {
   const p = event.payload;
-  const insertCols = {
-    id: event.aggregateId,
-    tenant_id: event.tenantId,
-    thread_key: p.threadKey,
+  const mutable = {
     subject: p.subject,
-    last_message_at: p.lastMessageAtIso,
-    message_count: p.messageCount,
+    lastMessageAt: p.lastMessageAtIso,
+    messageCount: p.messageCount,
   };
-  await upsertProjectionRow(
+  await upsertOnConflict(
     tx,
-    tableNameOf(mailThreadsProjectionTable),
-    insertCols,
-    [
-      `"subject" = EXCLUDED."subject"`,
-      `"last_message_at" = EXCLUDED."last_message_at"`,
-      `"message_count" = EXCLUDED."message_count"`,
-    ],
-    Object.values(insertCols),
+    mailThreadsProjectionMeta,
+    {
+      id: event.aggregateId,
+      tenantId: event.tenantId,
+      threadKey: p.threadKey,
+      ...mutable,
+    },
+    { conflictKeys: ["id"], update: mutable },
   );
 });

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/workflow-runner/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "The resume job reads due runs through the job's TenantDb",
+    "detail": "`selectDueWorkflowRunPending` takes a `TenantDb` and returns `{ runId, stepIndex }` rows, so the tenant filter comes from the TenantDb instead of a hand-written `WHERE tenant_id`.",
+    "migration": "keine"
+  },
   {
     "version": "0.339.0",
     "type": "breaking",

package/packages/bundled-features/src/workflow-runner/db/queries/due-runs.ts

@@ -1,8 +1,7 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { sql, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { workflowRunPendingTable } from "../../tables.js";
 
-export type DueRow = { readonly run_id: string; readonly step_index: number };
+export type DueRow = { readonly runId: string; readonly stepIndex: number };
 
 // Oldest first and capped, so a backlog after an outage drains over several
 // ticks instead of holding one tick's `concurrency: "skip"` slot for minutes.
@@ -12,13 +11,11 @@ export const DUE_RUNS_BATCH_SIZE = 100;
 // (ctx.tryAppendEvent on WORKFLOW_RESUMED) — a second dispatch for the same
 // row loses that race and no-ops. No row locks: in an autocommit statement
 // they would be released right after the SELECT and guard nothing.
-export async function selectDueWorkflowRunPending(
-  db: DbConnection,
-  tenantId: TenantId,
-): Promise<readonly DueRow[]> {
-  // kumiko-lint-ignore raw-sql tenant-scoped due-row pickup
-  return (await asRawClient(db).unsafe(
-    `SELECT run_id, step_index FROM workflow_run_pending WHERE tenant_id = $1 AND wake_at < now() ORDER BY wake_at ASC LIMIT ${DUE_RUNS_BATCH_SIZE}`,
-    [tenantId],
-  )) as readonly DueRow[];
+// `now()` stays the DB clock so job-host clock skew cannot mark rows due early.
+export function selectDueWorkflowRunPending(db: TenantDb): Promise<readonly DueRow[]> {
+  return db.selectMany<DueRow>(
+    workflowRunPendingTable,
+    { wakeAt: { lt: sql`now()` } },
+    { orderBy: { col: "wakeAt", direction: "asc" }, limit: DUE_RUNS_BATCH_SIZE },
+  );
 }

package/packages/bundled-features/src/workflow-runner/feature.ts

@@ -24,7 +24,6 @@
 //
 // wait/retry/waitForEvent suspensions all resume automatically now.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { selectDueWorkflowRunPending } from "./db/queries/due-runs.js";
 import { resumeRunHandler } from "./handlers/resume-run.write.js";
@@ -68,26 +67,20 @@ export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
         return;
       }
 
-      ctx.systemDb.assertTenantMatch(tenantId);
-      const dueRows = await selectDueWorkflowRunPending(
-        ctx.systemDb.unsafeRaw(
-          "due-row pickup needs FOR UPDATE SKIP LOCKED raw SQL; the query filters by this job's tenantId",
-        ) as DbConnection, // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
-        tenantId,
-      );
+      const dueRows = await selectDueWorkflowRunPending(ctx.systemDb.assertTenantMatch(tenantId));
 
       for (const row of dueRows) {
         try {
           await ctx.write("workflow-runner:write:resume-run", {
-            runId: row.run_id,
-            stepIndex: row.step_index,
+            runId: row.runId,
+            stepIndex: row.stepIndex,
           });
         } catch (error) {
           // skip: one row's dispatch failing (infra hiccup, not a business
           // outcome — resume-run itself never throws for expected cases)
           // must not stop the rest of this tenant's due rows from resuming.
           ctx.log.warn(
-            `[workflow-runner:resume-due-runs] runId=${row.run_id} stepIndex=${row.step_index} dispatch failed: ${String(error)}`,
+            `[workflow-runner:resume-due-runs] runId=${row.runId} stepIndex=${row.stepIndex} dispatch failed: ${String(error)}`,
           );
         }
       }

package/packages/bundled-features/src/billing-foundation/db/queries/payment-projection.ts

@@ -1,19 +0,0 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-// INSERT-once, not UPSERT: unlike subscriptionsProjectionTable (one row per
-// tenant, state overwritten on every event), a payment row is an immutable
-// fact keyed by paymentRowId(tenantId, providerName, providerEventId) — ON
-// CONFLICT DO NOTHING makes a projection rebuild/replay idempotent without
-// ever mutating an existing row.
-export async function insertPaymentProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
-  // kumiko-lint-ignore raw-sql tableName + column keys are code-controlled, not user input: tableName is buildEntityTable()'s static table name and insertKeys come from applyPaymentReceived's hardcoded object-literal columns in projection.ts — only values flow through $1..$n
-  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
-}

package/packages/bundled-features/src/billing-foundation/db/queries/subscription-projection.ts

@@ -1,15 +0,0 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-export async function upsertSubscriptionProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-  setClauses: readonly string[],
-  params: readonly unknown[],
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
-  await asRawClient(tx).unsafe(sqlText, params);
-}

package/packages/bundled-features/src/inbound-mail-foundation/db/queries/inbound-projections.ts

@@ -1,38 +0,0 @@
-// Raw-SQL-Helper für die inline projections — Muster
-// billing-foundation/db/queries/subscription-projection.ts.
-//
-// Warum raw statt drizzle-insert: die apply-fns laufen in der event-TX
-// mit einem DbRunner, und die ON-CONFLICT-Semantik (UPSERT vs.
-// DO NOTHING) ist der fachliche Kern — explizit hingeschrieben statt
-// hinter einem ORM-Builder versteckt.
-
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-
-/** INSERT ... ON CONFLICT ("id") DO UPDATE SET <setClauses>. */
-export async function upsertProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-  setClauses: readonly string[],
-  params: readonly unknown[],
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
-  await asRawClient(tx).unsafe(sqlText, params);
-}
-
-/** INSERT ... ON CONFLICT ("id") DO NOTHING — für append-only-Rows
- *  (inbound-message: genau EIN received-event pro Stream, Replays
- *  no-op'en auf der PK). */
-export async function insertIgnoreProjectionRow(
-  tx: DbRunner,
-  tableName: string,
-  insertCols: Record<string, unknown>,
-): Promise<void> {
-  const insertKeys = Object.keys(insertCols);
-  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
-  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
-  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
-}