@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,257 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { userSessionTable } from "../../sessions/index.js";
+import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.js";
+import { userTable } from "../../user/index.js";
+import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table.js";
+import { tenantMembershipsTable } from "../membership-table.js";
+
+const KMS_POOL_CONCURRENCY = 4;
+
+type TeamStatus = "active" | "pending";
+
+type TeamRow = {
+  readonly id: string;
+  readonly userId: string | null;
+  readonly email: string | null;
+  readonly displayName: string | null;
+  readonly roles: readonly string[];
+  readonly status: TeamStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly lastSeenAt: Temporal.Instant | null;
+  readonly expiresAt: Temporal.Instant | null;
+};
+
+// The /members screen exposes one column per field above under the SAME
+// name — unlike delivery-log there is no display-alias to map, `sort` on
+// the wire already names a TeamRow field directly.
+const SORT_FIELDS = ["email", "status", "createdAt", "lastSeenAt"] as const;
+type SortField = (typeof SORT_FIELDS)[number];
+
+function isSortField(value: string): value is SortField {
+  return (SORT_FIELDS as readonly string[]).includes(value);
+}
+
+// Nulls (no session yet, invitation rows) sort last regardless of
+// direction — "unknown" reads as "least recent", not as a magic minimum
+// that flips to the top on `desc`.
+function compareTeamRows(a: TeamRow, b: TeamRow, field: SortField, dir: "asc" | "desc"): number {
+  const sign = dir === "asc" ? 1 : -1;
+  if (field === "createdAt") return Temporal.Instant.compare(a.createdAt, b.createdAt) * sign;
+  if (field === "lastSeenAt") {
+    if (a.lastSeenAt === null && b.lastSeenAt === null) return 0;
+    if (a.lastSeenAt === null) return 1;
+    if (b.lastSeenAt === null) return -1;
+    return Temporal.Instant.compare(a.lastSeenAt, b.lastSeenAt) * sign;
+  }
+  const av = field === "email" ? (a.email ?? "") : a.status;
+  const bv = field === "email" ? (b.email ?? "") : b.status;
+  return av.localeCompare(bv) * sign;
+}
+
+// User-selected facet filters (payload.filters, fw#2224) — `status` is the
+// only filterable field here: it's synthesized from which table a row came
+// from, not a stored column, so there is nothing else meaningful to filter
+// on server-side yet. `filter` (singular, screen-level static filter) is
+// accepted for schema-shape parity but unused — no /members screen sets one.
+function matchesStatusFilter(
+  row: TeamRow,
+  filters: readonly { field: string; value: unknown }[],
+): boolean {
+  const statusFilter = filters.find((f) => f.field === "status");
+  if (statusFilter === undefined) return true;
+  const allowed = Array.isArray(statusFilter.value) ? statusFilter.value : [statusFilter.value];
+  return allowed.includes(row.status);
+}
+
+export const teamListQuery = definePagedQueryHandler({
+  name: "team:list",
+  schema: z.object({
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(50),
+    offset: z.number().int().nonnegative().optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+    search: z.string().optional(),
+    totalCount: z.boolean().optional(),
+    filter: z
+      .object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        value: z.unknown(),
+      })
+      .optional(),
+    filters: z
+      .array(
+        z.object({
+          field: z.string(),
+          op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+          value: z.unknown(),
+        }),
+      )
+      .optional(),
+  }),
+  access: { roles: access.admin },
+  description:
+    "Pages through the caller's tenant team as one list of active members and pending invitations, with email, display name, roles, last-seen time and a status of active or pending, sortable and filterable by status.",
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:team:list requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const tenantId = query.user.tenantId;
+
+    const membershipRows = await selectMany(db, tenantMembershipsTable, { tenantId });
+    const userIds = [...new Set(membershipRows.map((row) => String(row["userId"])))];
+    const users =
+      userIds.length > 0
+        ? await selectMany<{ id: unknown; email?: unknown; displayName?: unknown }>(db, userTable, {
+            id: userIds,
+          })
+        : [];
+
+    const lastSeenByUserId = new Map<string, Temporal.Instant>();
+    if (userIds.length > 0) {
+      try {
+        const sessions = await selectMany<{ userId: unknown; lastSeenAt: unknown }>(
+          db,
+          userSessionTable,
+          { tenantId, userId: userIds },
+        );
+        for (const session of sessions) {
+          const value = session["lastSeenAt"];
+          if (!(value instanceof Temporal.Instant)) continue;
+          const userId = String(session["userId"]);
+          const current = lastSeenByUserId.get(userId);
+          if (current === undefined || Temporal.Instant.compare(value, current) > 0) {
+            lastSeenByUserId.set(userId, value);
+          }
+        }
+      } catch (err) {
+        // ponytail: lean sample apps (admin-console) mount auth without
+        // sessions — store_user_sessions never gets pushed. Integration tests
+        // may seed the table without mounting the feature; prod mounts both.
+        if ((err as { code?: string }).code !== "42P01") throw err;
+      }
+    }
+
+    // Bounded, not Promise.all/sequential-per-item: shares the KMS
+    // adapter's small dedicated pool (max 4, see members.query.ts) with the
+    // invitations decrypt below — the two passes run one after the other
+    // (await, not Promise.all), so combined concurrency never exceeds 4.
+    const decryptedUsers = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {
+      const email =
+        typeof user.email === "string"
+          ? await decryptStoredPii(user.email, "email", "tenant:team-list")
+          : null;
+      const displayName =
+        typeof user.displayName === "string"
+          ? await decryptStoredPii(user.displayName, "displayName", "tenant:team-list")
+          : null;
+      return { userId: String(user.id), email, displayName };
+    });
+    const decryptedByUserId = new Map(decryptedUsers.map((d) => [d.userId, d]));
+
+    const memberRows: TeamRow[] = membershipRows.map((row) => {
+      const userId = String(row["userId"]);
+      const decrypted = decryptedByUserId.get(userId);
+      const createdAt = row["insertedAt"];
+      return {
+        id: String(row["id"]),
+        userId,
+        email: decrypted?.email ?? null,
+        displayName: decrypted?.displayName ?? null,
+        roles: parseRoles(row["roles"]),
+        status: "active",
+        createdAt: createdAt instanceof Temporal.Instant ? createdAt : Temporal.Now.instant(),
+        lastSeenAt: lastSeenByUserId.get(userId) ?? null,
+        expiresAt: null,
+      };
+    });
+
+    // Pending only — accepted/cancelled/expired invitations don't belong on
+    // this screen (accepted ones already surfaced as a membership row above;
+    // the rest is history for a separate audit feature). SQL-side filter,
+    // same rationale as invitations.query.ts.
+    const pendingInvitations = await selectMany<Record<string, unknown>>(
+      db,
+      tenantInvitationsTable,
+      { tenantId, status: INVITATION_STATUS.pending },
+    );
+    const invitationRows: TeamRow[] = await mapWithConcurrency(
+      pendingInvitations,
+      KMS_POOL_CONCURRENCY,
+      async (row): Promise<TeamRow> => {
+        const email = row["email"];
+        const decryptedEmail =
+          typeof email === "string"
+            ? await decryptStoredPii(email, "email", "tenant:team-list")
+            : null;
+        const createdAt = row["insertedAt"];
+        const expiresAt = row["expiresAt"];
+        return {
+          id: String(row["id"]),
+          userId: null,
+          email: decryptedEmail,
+          displayName: null,
+          roles: typeof row["role"] === "string" ? [row["role"]] : [],
+          status: "pending",
+          createdAt: createdAt instanceof Temporal.Instant ? createdAt : Temporal.Now.instant(),
+          lastSeenAt: null,
+          expiresAt: expiresAt instanceof Temporal.Instant ? expiresAt : null,
+        };
+      },
+    );
+
+    // Merge → filter → sort → slice, in that order: `total` and the page
+    // window both have to be computed against the FILTERED set, not the raw
+    // merge, or the pager and the status-facet disagree with each other.
+    //
+    // ponytail: reads both tables fully and merges/sorts/slices in JS —
+    // there is no cursor. A cursor over a list merged from two tables in
+    // application code is either wrong (each source paginates
+    // independently, so page boundaries don't line up) or has to read
+    // everything anyway to know where the boundary falls. This holds up to
+    // the order of a few thousand members per tenant; past that the fix is
+    // a real combined read-projection (a materialized view/table kept in
+    // sync by both tenant-membership and tenant-invitation events), not a
+    // cursor bolted onto this merge. Upgrade path: r.multiStreamProjection({
+    // name, apply }) — see custom-fields/wire-for-entity.ts,
+    // feature-toggles/feature.ts, step-dispatcher/feature.ts.
+    const search = query.payload.search?.trim().toLowerCase();
+    const merged = [...memberRows, ...invitationRows].filter((row) => {
+      if (search === undefined || search === "") return true;
+      return (
+        (row.email?.toLowerCase().includes(search) ?? false) ||
+        (row.displayName?.toLowerCase().includes(search) ?? false)
+      );
+    });
+    const filtered = merged.filter((row) => matchesStatusFilter(row, query.payload.filters ?? []));
+
+    const requestedSort = query.payload.sort;
+    const sortField: SortField =
+      requestedSort !== undefined && isSortField(requestedSort) ? requestedSort : "createdAt";
+    const sortDirection = query.payload.sortDirection ?? "desc";
+    const sorted = [...filtered].sort((a, b) => compareTeamRows(a, b, sortField, sortDirection));
+
+    const offset = query.payload.offset ?? 0;
+    const limit = query.payload.limit;
+    const page = sorted.slice(offset, offset + limit);
+
+    return {
+      rows: page,
+      nextCursor: null,
+      ...(query.payload.totalCount === true && { total: filtered.length }),
+    };
+  },
+});

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

@@ -0,0 +1,71 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tenantTable } from "../schema/tenant.js";
+import { isSystemAdmin } from "./is-system-admin.js";
+
+// Label source behind every `tenant:tenant` reference column (fw#3142). The
+// entity-convention lookup, tenant:query:tenant:list, is a SystemAdmin-only
+// entity-list handler, so a TenantAdmin got a 403 and every tenant cell fell
+// back to the raw UUID. A SystemAdmin keeps the global reach tenant:list gave
+// them; a TenantAdmin only ever sees their own tenant.
+// ponytail: capped at `limit` (200 list lookup, 50 combobox) like every
+// reference lookup; beyond that the cell falls back to the raw id.
+// A search filters in memory over a bounded scan so the combobox can reach
+// tenants beyond the first `limit`; the cap keeps it from reading every tenant.
+const SEARCH_SCAN_CAP = 1000;
+
+export const tenantDirectoryQuery = definePagedQueryHandler({
+  name: "tenantDirectory",
+  schema: z.object({
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT),
+    // Sent by the reference combobox while the user types.
+    search: z.string().trim().min(1).optional(),
+  }),
+  access: { roles: access.admin },
+  description:
+    "Lists tenants as id/label pairs for resolving tenant references to display names: the caller's own tenant for an admin, every tenant for a SystemAdmin.",
+  agent: { expose: false },
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:query:tenant-directory requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+    const { limit, search } = query.payload;
+    const scanLimit = search === undefined ? limit : SEARCH_SCAN_CAP;
+    let tenants: readonly { id: unknown; name?: unknown }[];
+    if (isSystemAdmin(query.user)) {
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "SystemAdmin reference labels span every tenant, as tenant:query:tenant:list did",
+      );
+      tenants = await selectMany(db, tenantTable, undefined, {
+        limit: scanLimit,
+        orderBy: [
+          { col: "name", direction: "asc" },
+          { col: "id", direction: "asc" },
+        ],
+      });
+    } else {
+      const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
+      tenants = row ? [row] : [];
+    }
+    const labeled = tenants.map((tenant) => {
+      const id = String(tenant.id);
+      return { id, label: typeof tenant.name === "string" ? tenant.name : 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/packages/bundled-features/src/tenant/handlers/toggle-enabled.write.ts

@@ -0,0 +1,37 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant.js";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+// Admin flip: last-writer-wins is fine. SystemAdmin is the only caller and
+// there's no meaningful concurrent-edit race on this single boolean.
+function createToggleTenantHandler(enable: boolean) {
+  const verbName = enable ? "enable" : "disable";
+  return defineWriteHandler({
+    name: verbName,
+    schema: z.object({ id: z.uuid() }),
+    access: { roles: ["SystemAdmin"] },
+    description: enable
+      ? "Re-enables a disabled tenant so its members can sign in and switch to it again; this is the undo for tenant:write:disable."
+      : "Marks a tenant disabled so it stops counting as a membership — its members can no longer sign in to it or switch to it — while leaving all of its data in place.",
+    handler: async (event, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: `tenant:write:${verbName} requires ctx.systemDb — is r.systemScope() still set on the tenant feature?`,
+        });
+      }
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "SystemAdmin enables/disables tenants platform-wide",
+      );
+      return crud.update({ id: event.payload.id, changes: { isEnabled: enable } }, event.user, db, {
+        skipOptimisticLock: true,
+      }); // @wrapper-known semantic-alias
+    },
+  });
+}
+
+export const enableWrite = createToggleTenantHandler(true);
+export const disableWrite = createToggleTenantHandler(false);

package/packages/bundled-features/src/tenant/handlers/update-member-roles.write.ts

@@ -0,0 +1,208 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, type DbRow } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  assignableAppRolesOf,
+  createSystemUser,
+  defineWriteHandler,
+  findForbiddenRoleAssignment,
+  mergeAssignedRoles,
+  SYSTEM_ROLE,
+  withResponseData,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  NotFoundError,
+  ValidationError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { assertNotLastTenantAdmin } from "../last-tenant-admin.js";
+import {
+  findForbiddenMembershipRole,
+  reservedMembershipRoleError,
+  unassignableMembershipRoleError,
+} from "../membership-roles.js";
+import { tenantMembershipEntity, tenantMembershipsTable } from "../membership-table.js";
+
+const executor = createEventStoreExecutor(tenantMembershipsTable, tenantMembershipEntity, {
+  entityName: "tenant-membership",
+});
+
+// Literal QN, not an import off the sessions feature — tenant is
+// foundational and must boot without sessions mounted (no r.requires/
+// r.usesApi here, unlike user-data-rights:restrict-account's hard dep).
+const REVOKE_ALL_SESSIONS_QN = "sessions:write:user-session:revoke-all-for-user";
+
+/** SystemAdmin may pass payload.tenantId (cross-tenant); the members actionForm
+ *  only sends userId+roles, so fall back to the active session tenant. */
+function resolveTargetTenantId(
+  isSystem: boolean,
+  payloadTenantId: string | undefined,
+  sessionTenantId: string | undefined,
+): string | undefined {
+  return isSystem ? (payloadTenantId ?? sessionTenantId) : sessionTenantId;
+}
+
+// Editing your OWN roles keeps the current session: roles are re-derived per
+// request, so the new roles apply at once without a re-login. Other sessions
+// of that user and any foreign edit still revoke all.
+function revokeSessionsPayload(
+  targetUserId: string,
+  targetTenantId: string,
+  actor: { readonly id: string; readonly sid?: string | undefined },
+): { userId: string; tenantId: string; exceptSessionId?: string } {
+  const payload = { userId: targetUserId, tenantId: targetTenantId };
+  if (targetUserId !== actor.id || actor.sid === undefined) return payload;
+  return { ...payload, exceptSessionId: actor.sid };
+}
+
+export const updateMemberRolesWrite = defineWriteHandler({
+  name: "updateMemberRoles",
+  schema: z.object({
+    userId: z.string().min(1),
+    tenantId: z.string().optional(),
+    roles: z.array(z.string()).min(1),
+  }),
+  // "system" + access.admin ("TenantAdmin", "Admin", "SystemAdmin").
+  // The system user (createSystemUser, roles=["system"]) and SystemAdmin
+  // manage memberships cross-tenant (payload.tenantId). TenantAdmin and Admin
+  // are session-scoped (event.user.tenantId).
+  access: { roles: ["system", ...access.admin] },
+  description:
+    "Sets the roles a user holds in a tenant, rejecting reserved role names and any grant that would raise the target above the caller; roles the caller could not grant (platform roles such as DataProtectionOfficer or TenantOwner, undeclared or higher-tier app roles) are kept, only the system user replaces the full list; admins act on their own tenant, SystemAdmins on any.",
+  handler: async (event, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:updateMemberRoles requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+
+    const isSystemActor = event.user.roles.includes(SYSTEM_ROLE);
+    const isSystem = event.user.roles.includes("SystemAdmin") || isSystemActor;
+    const assignableAppRoles = assignableAppRolesOf(ctx.registry);
+    const targetTenantId = resolveTargetTenantId(
+      isSystem,
+      event.payload.tenantId,
+      event.user.tenantId,
+    );
+    if (!targetTenantId) {
+      return writeFailure(
+        new ValidationError({
+          fields: [
+            {
+              path: "tenantId",
+              code: "required",
+              i18nKey: "errors.validation.required",
+            },
+          ],
+        }),
+      );
+    }
+    const db = isSystem
+      ? ctx.systemDb.acknowledgeCrossTenant("SystemAdmin manages memberships across tenants")
+      : ctx.systemDb.assertTenantMatch(event.user.tenantId);
+
+    const forbidden = findForbiddenMembershipRole(event.payload.roles);
+    if (forbidden !== undefined) return writeFailure(reservedMembershipRoleError(forbidden));
+
+    const existing = await fetchOne(db, tenantMembershipsTable, {
+      userId: event.payload.userId,
+      tenantId: targetTenantId,
+    });
+    if (!existing) {
+      return writeFailure(
+        new NotFoundError("membership", undefined, {
+          i18nKey: "tenant.errors.membershipNotFound",
+          i18nParams: { userId: event.payload.userId, tenantId: targetTenantId },
+        }),
+      );
+    }
+
+    const row = existing as DbRow; // @cast-boundary generic-record
+    const currentTargetRoles = parseRoles(row["roles"]);
+
+    if (!isSystemActor) {
+      const forbiddenElevation = findForbiddenRoleAssignment(
+        event.user.roles,
+        event.payload.roles,
+        currentTargetRoles,
+        assignableAppRoles,
+      );
+      if (forbiddenElevation !== undefined) {
+        return writeFailure(unassignableMembershipRoleError(forbiddenElevation));
+      }
+    }
+
+    // The system user is programmatic and replaces; human actors keep what they cannot grant.
+    const nextRoles = isSystemActor
+      ? event.payload.roles
+      : mergeAssignedRoles(
+          event.user.roles,
+          event.payload.roles,
+          currentTargetRoles,
+          assignableAppRoles,
+        );
+
+    const targetIsTenantAdmin = currentTargetRoles.includes("TenantAdmin");
+    const willBeTenantAdmin = nextRoles.includes("TenantAdmin");
+
+    if (targetIsTenantAdmin && !willBeTenantAdmin) {
+      // assertNotLastTenantAdmin issues raw SQL, so it needs the raw runner, not
+      // `db` — the count is already filtered by the explicit targetTenantId.
+      const lockRunner = ctx.systemDb.unsafeRaw(
+        "tenant:write:updateMemberRoles last-TenantAdmin advisory lock + membership count",
+      );
+      const lastAdmin = await assertNotLastTenantAdmin(
+        lockRunner,
+        targetTenantId,
+        event.payload.userId,
+      );
+      if (lastAdmin !== undefined) return lastAdmin;
+    }
+
+    // fetchOne already gave us the stream version — hand it to the executor
+    // instead of skipping the lock. Race window (another admin writing
+    // between this read and append) surfaces as version_conflict rather than
+    // silent overwrite. Per-membership parallelism is rare; if it happens,
+    // the client retries on the error.
+    //
+    // A role change can be security-relevant (e.g. demoting an Admin) — the
+    // user must re-authenticate with the new roles, everywhere. Revoke BEFORE
+    // the update closes the window where the demoted user keeps a valid
+    // session until the revoke write lands. Best-effort cross-feature call:
+    // sessions may not be mounted (registry lookup instead of a hard
+    // requires, see above).
+    const revoker = ctx.registry.getWriteHandler(REVOKE_ALL_SESSIONS_QN);
+    if (revoker) {
+      await ctx.writeAs(
+        createSystemUser(targetTenantId),
+        REVOKE_ALL_SESSIONS_QN,
+        revokeSessionsPayload(event.payload.userId, targetTenantId, event.user),
+      );
+    }
+
+    // Stream tenant follows the actor via streamTenantFor — use the
+    // membership tenant so SystemAdmin/cross-tenant and TenantAdmin paths
+    // hit the same stream seedTenantMembership/invite-accept wrote.
+    // Keep the real actor for audit metadata; only override tenantId so
+    // streamTenantFor writes into the membership tenant (#2401).
+    const result = await executor.update(
+      {
+        id: row["id"] as string, // @cast-boundary db-row
+        version: row["version"] as number, // @cast-boundary db-row
+        changes: { roles: JSON.stringify(nextRoles) },
+      },
+      { ...event.user, tenantId: targetTenantId },
+      db,
+    );
+
+    return withResponseData(result, {
+      ...event.payload,
+      roles: nextRoles,
+      tenantId: targetTenantId,
+    });
+  },
+});

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

@@ -0,0 +1,55 @@
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  InternalError,
+  NotFoundError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant.js";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+export const updateWrite = defineWriteHandler({
+  name: "update",
+  schema: z.object({
+    id: z.uuid(),
+    // Clients must send the version they read. The CrudExecutor rejects
+    // missing versions with version_conflict — see the optimistic-locking
+    // design note in crud-executor.ts.
+    version: z.number(),
+    changes: z.object({ name: z.string().min(1).max(200).optional() }),
+  }),
+  access: { roles: ["Admin", "SystemAdmin"] },
+  description:
+    "Renames a tenant against the version the caller read; an Admin may only rename their own tenant, a SystemAdmin any of them.",
+  handler: async (event, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "tenant:write:update requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
+      });
+    }
+
+    // "Admin" is tenant-scoped and must not touch another tenant's row —
+    // SystemAdmin is the platform-wide role and stays cross-tenant by design.
+    if (event.user.roles.includes("SystemAdmin")) {
+      const db = ctx.systemDb.acknowledgeCrossTenant("SystemAdmin is platform-wide by design");
+      return crud.update(event.payload, event.user, db);
+    }
+
+    let db: TenantDb;
+    try {
+      db = ctx.systemDb.assertTenantMatch(event.payload.id);
+    } catch (err) {
+      // Kept as tenant_not_found (not the underlying access_denied) so a
+      // cross-tenant Admin can't use the error to enumerate tenant existence.
+      if (err instanceof AccessDeniedError) {
+        return writeFailure(new NotFoundError("tenant", event.payload.id));
+      }
+      throw err;
+    }
+    return crud.update(event.payload, event.user, db);
+  },
+});