@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/template-resolver/template-delivery-policy.ts

@@ -1,6 +1,5 @@
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { isSystemAdmin } from "./template-draft.ts";
 import { SYSTEM_TENANT_ID } from "./web/constants.ts";
 import { TEMPLATE_RESOLVER_FEATURE } from "./web/qualified-names.ts";
 
@@ -45,16 +44,6 @@ export function isRowServed(
   return row.tenantId === SYSTEM_TENANT_ID || isTenantOverrideServed(policy, row);
 }
 
-// A SystemAdmin sees every stored row, so a locked override can still be reset; everyone else
-// sees only what is delivered, which keeps a locked override out of the template-resolver queries for a TenantAdmin (the audit log keeps the history).
-export function isRowServedTo(
-  policy: TemplateDeliveryPolicy,
-  user: { readonly roles: readonly string[] },
-  row: DeliveryTarget & { readonly tenantId: string },
-): boolean {
-  return isSystemAdmin(user) || isRowServed(policy, row);
-}
-
 function isDeliveryTarget(value: unknown): value is DeliveryTarget {
   return (
     typeof propertyOf(value, "kind") === "string" && typeof propertyOf(value, "slug") === "string"

package/packages/bundled-features/src/template-resolver/template-meta.ts

@@ -6,6 +6,12 @@ import {
   type TemplateKind,
 } from "./web/constants.ts";
 import { MAIL_TONES, type MailTone } from "./web/mail-constants.ts";
+import {
+  MAIL_LAYOUT_ACCENT_LINES,
+  MAIL_LAYOUT_BUTTON_STYLES,
+  MAIL_LAYOUT_FONTS,
+  MAIL_LAYOUT_WIDTHS,
+} from "./web/mail-layout-constants.ts";
 
 // One or more kebab segments joined by ":" — notification templates are seeded
 // under their qualified name `feature:notify:name`.
@@ -89,13 +95,15 @@ const pdfMetaSchema = z
   })
   .strict();
 
-const MAIL_LAYOUT_FONTS = ["sans", "serif"] as const;
-const MAIL_LAYOUT_ACCENT_LINES = ["branding", "none"] as const;
-const MAIL_LAYOUT_BUTTON_STYLES = ["filled-rounded", "filled-square", "outline"] as const;
+const MAIL_LAYOUT_WIDTH_LITERALS = [
+  z.literal(MAIL_LAYOUT_WIDTHS[0]),
+  z.literal(MAIL_LAYOUT_WIDTHS[1]),
+  z.literal(MAIL_LAYOUT_WIDTHS[2]),
+] as const;
 
 const mailLayoutMetaSchema = z
   .object({
-    width: z.union([z.literal(560), z.literal(600), z.literal(640)]).optional(),
+    width: z.union(MAIL_LAYOUT_WIDTH_LITERALS).optional(),
     font: z.enum(MAIL_LAYOUT_FONTS).optional(),
     outerBackground: z.string().regex(HEX_COLOR_PATTERN, "must be a #rrggbb color").optional(),
     accentLine: z.enum(MAIL_LAYOUT_ACCENT_LINES).optional(),

package/packages/bundled-features/src/template-resolver/template-preview.ts

@@ -28,7 +28,12 @@ import {
   RendererError,
   type RendererPlugin,
 } from "../renderer-foundation/index.ts";
-import { createTemplateResolverApi, TemplateNotFoundError, type TemplateResource } from "./api.ts";
+import {
+  createTemplateResolverApi,
+  isRowDeliveredTo,
+  TemplateNotFoundError,
+  type TemplateResource,
+} from "./api.ts";
 import { collectDocumentResourceKeys } from "./compile-document-body.ts";
 import { parseStoredJson } from "./handlers/template-gates.ts";
 import { validateTemplateDraft } from "./handlers/validate.query.ts";
@@ -41,7 +46,7 @@ import {
 import { type LinkedResourceEntry, parseLinkedResourceEntries } from "./linked-resources.ts";
 import { buildDisplayHtml } from "./preview-display-html.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
-import { deliveryPolicyOf, isRowServedTo } from "./template-delivery-policy.ts";
+import { deliveryPolicyOf } from "./template-delivery-policy.ts";
 import {
   isMailTemplateMeta,
   type MailTemplateMeta,
@@ -327,7 +332,10 @@ async function loadEditedRowResources(
     { limit: 1 },
   );
   const row = rows[0];
-  if (row !== undefined && !isRowServedTo(deliveryPolicyOf(ctx.registry), user, row)) {
+  if (
+    row !== undefined &&
+    !(await isRowDeliveredTo(ctx.db, deliveryPolicyOf(ctx.registry), user, row))
+  ) {
     return undefined;
   }
   return row === undefined ? undefined : parseLinkedResourceEntries(row.linkedResources);

package/packages/bundled-features/src/template-resolver/web/client-plugin.tsx

@@ -173,7 +173,7 @@ function makeTreeProvider(tenantIdOverride?: string, collectionId?: string): Tre
     const headers: Record<string, string> = { "content-type": "application/json" };
     const csrf = readCsrfToken();
     if (csrf !== undefined) headers[CSRF_HEADER_NAME] = csrf;
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     fetch("/api/query", {
       method: "POST",
       headers,
@@ -344,7 +344,7 @@ function TextBlockEditor({
 
   // Sync loaded data into the form state. loaded === null means the block does
   // not exist yet — empty form for the create flow.
-  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+  // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
   useEffect(() => {
     if (loading) return;
     setTitle(loaded?.title ?? "");

package/packages/bundled-features/src/template-resolver/web/constants.ts

@@ -4,6 +4,8 @@
 // RenderKind identifies the consumer class of a template. Plugin renderers in
 // `renderer-foundation` match on kind; the resolver here is kind-agnostic: it
 // only loads, and the content format (markdown/mjml/html) decides who renders it.
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+
 export const RENDER_KINDS = ["mail", "document-pdf", "image-snapshot"] as const;
 export type RenderKind = (typeof RENDER_KINDS)[number];
 
@@ -55,8 +57,10 @@ export const COLLECTION_REFUSED_KINDS = [
   "pdf-layout",
 ] as const satisfies readonly TemplateKind[];
 
-export function isCollectionRefusedKind(kind: string): boolean {
-  return COLLECTION_REFUSED_KINDS.some((refused) => refused === kind);
+export function isCollectionRefusedKind(
+  kind: unknown,
+): kind is (typeof COLLECTION_REFUSED_KINDS)[number] {
+  return isOneOf(COLLECTION_REFUSED_KINDS, kind);
 }
 
 export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"] as const;
@@ -69,6 +73,7 @@ export const TEMPLATE_STATUSES = ["draft", "active", "archived"] as const;
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
 export const ACTIVE_TEMPLATE_STATUS = "active" satisfies TemplateStatus;
 
+export { HEX_COLOR_PATTERN } from "./mail-layout-constants.ts";
 export {
   PDF_DEFAULT_MARGIN_MM,
   PDF_FOOTER_MARGIN_MM,
@@ -79,9 +84,6 @@ export {
   type PdfPageFormat,
 } from "./pdf-constants.ts";
 
-// Colors end up inside MJML attributes, so only a strict hex is ever written there.
-export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
-
 export const DEFAULT_MAIL_LAYOUT_SLUG = "default";
 export const DEFAULT_PDF_LAYOUT_SLUG = "default";
 

package/packages/bundled-features/src/template-resolver/web/index.ts

@@ -16,6 +16,13 @@ export {
   PDF_DOCUMENT_BLOCKS,
 } from "./document-toolbar-blocks.ts";
 export { MAIL_TONES, type MailTone } from "./mail-constants.ts";
+export {
+  HEX_COLOR_PATTERN,
+  MAIL_LAYOUT_ACCENT_LINES,
+  MAIL_LAYOUT_BUTTON_STYLES,
+  MAIL_LAYOUT_FONTS,
+  MAIL_LAYOUT_WIDTHS,
+} from "./mail-layout-constants.ts";
 export {
   PDF_DEFAULT_MARGIN_MM,
   PDF_FOOTER_MARGIN_MM,

package/packages/bundled-features/src/template-resolver/web/mail-layout-constants.ts

@@ -0,0 +1,8 @@
+// No imports: web/ re-exports these, and template-meta.ts pulls in zod and the framework engine.
+export const MAIL_LAYOUT_WIDTHS = [560, 600, 640] as const;
+export const MAIL_LAYOUT_FONTS = ["sans", "serif"] as const;
+export const MAIL_LAYOUT_ACCENT_LINES = ["branding", "none"] as const;
+export const MAIL_LAYOUT_BUTTON_STYLES = ["filled-rounded", "filled-square", "outline"] as const;
+
+// Colors end up inside MJML attributes, so only a strict hex is ever written there.
+export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Tenant directory search contract documented",
+    "detail": "A search returns the first limit matches in tenant-key order, sorted by label afterwards; the handler description now says so."
+  },
   {
     "version": "0.383.0",
     "type": "improvement",

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

@@ -98,10 +98,10 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
 
     r.config({
       keys: {
-        // Stammdaten-Settings — Tenant-Admin darf ändern, alle dürfen lesen.
+        // Core tenant settings — tenant admins can change them; all users can read them.
         companyName: createTenantConfig("text", { default: "" }),
-        // Pragmatisch kuratierte Liste — IANA hat hunderte, hier die in der
-        // Praxis relevantesten. Erweiterung später wenn echter Bedarf.
+        // Curated subset of IANA time zones covering the most relevant practical cases.
+        // Extend it when a real need arises.
         timezone: createTenantConfig("select", {
           default: "Europe/Berlin",
           options: [
@@ -124,8 +124,8 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
           options: ["de", "en", "fr", "es"],
         }),
 
-        // SMTP — nur SystemAdmin (Plattform-Operator) ändert; smtpPass ist
-        // verschlüsselt + nur für SystemAdmin lesbar.
+        // SMTP settings — only SystemAdmin (platform operator) can change them; smtpPass is
+        // encrypted and readable only by SystemAdmin.
         smtpHost: createTenantConfig("text", { write: access.systemAdmin, read: access.admin }),
         smtpPass: createTenantConfig("text", {
           write: access.systemAdmin,
@@ -133,8 +133,8 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
           encrypted: true,
         }),
 
-        // System-Settings — nur programmatisch (SYSTEM_USER) änderbar,
-        // Tenant-Admin sieht readonly.
+        // System settings — changeable only programmatically by SYSTEM_USER;
+        // tenant admins see them as read-only.
         priceModel: createSystemConfig("select", {
           default: "basic",
           options: ["basic", "pro", "enterprise"],

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

@@ -32,7 +32,7 @@ async function loadMemberUserIds(db: TenantDb, tenantId: string): Promise<readon
   return [...new Set(memberships.map((row) => String(row["userId"])))].sort(compareIds);
 }
 
-// Label source behind every `user:user` reference column (fw#3107). The
+// Label source behind every `user:user` reference column. The
 // entity-convention lookup, user:query:user:list, is a SystemAdmin
 // cross-tenant roster, so a TenantAdmin got a 403 and every actor cell fell
 // back to the raw UUID. Deliberately narrower than tenant:query:members:
@@ -50,6 +50,8 @@ export const memberDirectoryQuery = definePagedQueryHandler({
     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(),
+    // Resolves exactly these users; callers that know their ids must not depend on the cap.
+    ids: z.array(z.string().min(1)).max(MAX_LIST_LIMIT).optional(),
   }),
   access: { roles: access.admin },
   description:
@@ -62,7 +64,8 @@ export const memberDirectoryQuery = definePagedQueryHandler({
           "tenant:query:member-directory requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
       });
     }
-    const { limit, search } = query.payload;
+    const { limit, search, ids } = query.payload;
+    if (ids?.length === 0) return { rows: [], nextCursor: null };
     // Without a search the first `limit` rows are enough; with one, every
     // candidate must be decrypted before the limit can apply.
     const scanLimit = search === undefined ? limit : SEARCH_SCAN_CAP;
@@ -71,13 +74,16 @@ export const memberDirectoryQuery = definePagedQueryHandler({
       const db = ctx.systemDb.acknowledgeCrossTenant(
         "SystemAdmin reference labels span every tenant, as user:query:user:list did",
       );
-      users = await selectMany(db, userTable, undefined, {
+      users = await selectMany(db, userTable, ids === undefined ? undefined : { id: ids }, {
         limit: scanLimit,
         orderBy: { col: "id", direction: "asc" },
       });
     } else {
       const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
-      const userIds = (await loadMemberUserIds(db, query.user.tenantId)).slice(0, scanLimit);
+      const requestedIds = ids === undefined ? undefined : new Set(ids);
+      const userIds = (await loadMemberUserIds(db, query.user.tenantId))
+        .filter((id) => requestedIds === undefined || requestedIds.has(id))
+        .slice(0, scanLimit);
       users =
         userIds.length > 0
           ? await selectMany(

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

@@ -20,7 +20,7 @@ export const membersQuery = defineQueryHandler({
   name: "members",
   schema: z.object({
     // Optional single-user filter — audit detail (and similar) only need one
-    // member's display name, not the full decrypted roster (fw#2291).
+    // member's display name, not the full decrypted roster.
     userId: z.string().min(1).optional(),
   }),
   access: { roles: access.admin },

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

@@ -31,7 +31,7 @@ export const membershipsQuery = defineQueryHandler({
     // tenantName/tenantKey make memberships distinguishable in the UI
     // (otherwise just the UUID prefix — seed tenants with a 00000000-…
     // prefix would be indistinguishable). A single IN-batch over all
-    // tenantIds instead of fetchOne per membership (#324).
+    // tenantIds instead of fetchOne per membership.
     type TenantRow = { id: unknown; name?: unknown; key?: unknown; isEnabled?: unknown };
     const tenants = await decryptTenantNames(
       await selectMany<TenantRow>(db, tenantTable, {

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

@@ -58,7 +58,7 @@ function compareTeamRows(a: TeamRow, b: TeamRow, field: SortField, dir: "asc" |
   return av.localeCompare(bv) * sign;
 }
 
-// User-selected facet filters (payload.filters, fw#2224) — `status` is the
+// User-selected facet filters (payload.filters) — `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

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

@@ -10,7 +10,7 @@ import { decryptTenantNames, takeTenantsMatchingDecryptedName } from "../decrypt
 import { tenantTable } from "../schema/tenant.ts";
 import { isSystemAdmin } from "./is-system-admin.ts";
 
-// Label source behind every `tenant:tenant` reference column (fw#3142). The
+// Label source for every `tenant:tenant` reference column. 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
@@ -27,10 +27,12 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
     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(),
+    // Resolves exactly these tenants; callers that know their ids must not depend on the cap.
+    ids: z.array(z.string().min(1)).max(MAX_LIST_LIMIT).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.",
+    "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. A search returns the first `limit` matches in tenant-key order (sorted by label afterwards), not the alphabetically best matches.",
   agent: { expose: false },
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
@@ -39,14 +41,15 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
           "tenant:query:tenant-directory requires ctx.systemDb — is r.systemScope() still set on the tenant feature?",
       });
     }
-    const { limit, search } = query.payload;
+    const { limit, search, ids } = query.payload;
+    if (ids?.length === 0) return { rows: [], nextCursor: null };
     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, {
+      tenants = await selectMany(db, tenantTable, ids === undefined ? undefined : { id: ids }, {
         limit: scanLimit,
         orderBy: [
           { col: "key", direction: "asc" },
@@ -56,7 +59,7 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
     } else {
       const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
       const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
-      tenants = row ? [row] : [];
+      tenants = row && (ids === undefined || ids.includes(query.user.tenantId)) ? [row] : [];
     }
     // name is ciphertext at rest, so the SQL page is keyed by the plaintext
     // `key`; label order and search happen in memory after decrypting.

package/packages/bundled-features/src/tenant/invitation-table.ts

@@ -1,26 +1,25 @@
-// Tenant-Invitations: Pre-Membership-Records mit Magic-Link-Token-Flow.
+// Tenant invitations are pre-membership records using a magic-link token flow.
 //
 // Lifecycle:
-//   1. Admin invitet email → DB-Row entsteht mit status="pending",
-//      Random-Token in Redis (signup-style bidirektional)
-//   2. Mail an die invited Email mit Activation-URL
-//   3. Klick auf Link → 3 Branches:
-//      a) Eingeloggt + Email matched session-user → Membership-Add
-//      b) Anonymous + Email existiert in users → Login → Auto-Accept
-//      c) Anonymous + Email neu → Password setzen → user+membership entstehen
-//   4. Bei Erfolg: status="accepted", token aus Redis gelöscht (single-use-burn)
-//   5. Bei Cancel durch Admin: status="cancelled", token aus Redis gelöscht
-//   6. Bei TTL-Ablauf: Redis räumt Token, DB-Row bleibt mit status="pending"
-//      (Cleanup-Job marked sie als "expired" — separater Concern)
+//   1. An admin invites an email → a DB row is created with status="pending",
+//      and a random token is stored in Redis (signup-style bidirectional flow).
+//   2. An email containing the activation URL is sent to the invitee.
+//   3. Clicking the link follows one of three branches:
+//      a) Logged in + email matches the session user → membership is added
+//      b) Anonymous + email exists in users → login → automatic acceptance
+//      c) Anonymous + new email → set a password → user and membership are created
+//   4. On success: status="accepted", and the Redis token is deleted (single-use).
+//   5. When cancelled by an admin: status="cancelled", and the Redis token is deleted.
+//   6. When the TTL expires: Redis removes the token, while the DB row remains
+//      status="pending" (a cleanup job marks it as "expired" separately).
 //
-// Single-Truth für expiry: Redis-TTL. DB-row.expiresAt ist nur UI-
-// Anzeige ("läuft in 6 Tagen ab"). Bei Lookup: pending in DB + token
-// nicht mehr in Redis → effectively expired, accept schlägt fehl mit
-// invalid-token.
+// Redis-TTL is the single source of truth for expiry. DB-row.expiresAt is only
+// for UI display ("expires in 6 days"). On lookup, a pending DB row without
+// a Redis token is effectively expired, so acceptance fails with invalid-token.
 //
-// Idempotenz: zweiter invite für gleiche (tenantId, email) während
-// pending → re-use existing row + refresh Redis-token + send mail
-// (analog zu signup-Resend).
+// Idempotency: a second invite for the same (tenantId, email) while pending
+// reuses the existing row, refreshes the Redis token, and sends the email
+// (analogous to signup resend).
 
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -34,9 +33,9 @@ import {
 // kumiko-lint-ignore cross-feature-import global-role options are owned by the user feature
 import { GLOBAL_ROLE_OPTIONS } from "../user/web/constants.ts";
 
-// Status-const-Object damit Handler-Code keine Magic-Strings nutzt.
-// Bei rename (z.B. "cancelled" → "revoked") fällt jeder caller auf
-// einmal auf statt verstreut über 5 Stellen.
+// The status constant object prevents handler code from using magic strings.
+// If a value is renamed (for example, "cancelled" → "revoked"), every caller
+// fails at once instead of having stale values scattered across five locations.
 export const INVITATION_STATUS = {
   pending: "pending",
   accepted: "accepted",
@@ -45,11 +44,10 @@ export const INVITATION_STATUS = {
 } as const;
 export type InvitationStatus = (typeof INVITATION_STATUS)[keyof typeof INVITATION_STATUS];
 
-// Order MUSS bit-identisch zur DB-Migration sein. Object.values
-// bewahrt insertion-order (JS-spec-stable für string-keys). Wenn
-// jemand INVITATION_STATUS reordnet, generiert drizzle-kit eine
-// neue Migration. Hardcoded-Tuple zur Sicherheit gegen versehentliches
-// Refactoring der Object-Keys.
+// The order MUST be bit-for-bit identical to the database migration. Object.values
+// preserves insertion order (stable for string keys under the JS spec). Reordering
+// INVITATION_STATUS generates a new drizzle-kit migration. The hardcoded tuple
+// also guards against accidental refactoring of the object keys.
 export const INVITATION_STATUSES = [
   INVITATION_STATUS.pending,
   INVITATION_STATUS.accepted,
@@ -60,11 +58,11 @@ export const INVITATION_STATUSES = [
 export const tenantInvitationEntity = createEntity({
   table: "read_tenant_invitations",
   fields: {
-    // Eingeladene Email — case-insensitive normalisiert beim Insert.
-    // PII bis zur Annahme (danach hat der User selbst seine email in users).
+    // The invited email is normalized case-insensitively on insert.
+    // It remains PII until acceptance; afterward, the user owns the email in users.
     email: createTextField({ required: true, maxLength: 320, personal: "self", find: "exact" }),
-    // Membership-Rolle die dem User nach Accept gegeben wird. Default
-    // im handler ist "Admin" (Co-Admin-Pattern für kleine Teams).
+    // The membership role granted to the user on acceptance. The handler defaults
+    // to "Admin" (a co-admin pattern for small teams).
     role: createTextField({
       required: true,
       maxLength: 50,
@@ -85,11 +83,11 @@ export const tenantInvitationEntity = createEntity({
       required: true,
       default: "pending",
     }),
-    // userId des einladenden Admins (für Audit-Trail "wer hat eingeladen").
+    // ID of the inviting admin, retained for the audit trail ("who invited").
     // Self-referencing ownerField: the field's own value IS the owner userId.
-    // lookupable: the delete-hook filters "invitations sent by this user"
-    // via the generated blind-index column instead of a full-tenant
-    // decrypt-and-scan (see user-data-rights-defaults' invitation hook).
+    // lookupable: the delete hook filters "invitations sent by this user"
+    // through the generated blind-index column instead of decrypting and scanning
+    // the entire tenant (see user-data-rights-defaults' invitation hook).
     invitedBy: createTextField({
       required: true,
       personal: { of: "invitedBy" },
@@ -103,11 +101,10 @@ export const tenantInvitationEntity = createEntity({
     // UI-Anzeige — Wahrheit liegt in Redis-TTL.
     expiresAt: createTimestampField({ required: true }),
   },
-  // Eine Invitation-Row pro (tenantId, email). Bei Re-Invite (Admin
-  // invitet zweite Mal nach Cancel/Accept) wird die existing row
-  // updated: status pending → cancelled → pending zurück, expiresAt
-  // refreshed. Verhindert Token-Doppel-Gabe + macht Resend-Idempotenz
-  // im handler trivial.
+  // One invitation row per (tenantId, email). On re-invite after cancellation or
+  // acceptance, the existing row is updated: status pending → cancelled → pending,
+  // and expiresAt is refreshed. This prevents duplicate tokens and makes resend
+  // idempotency trivial in the handler.
   indexes: [
     {
       unique: true,

package/packages/bundled-features/src/tenant/membership-table.ts

@@ -12,9 +12,9 @@ import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/eng
 // the old serial-id design and keeps duplicate-write protection at the
 // database level independent of the handler lookup.
 //
-// Single-Source-of-Truth: `tenantMembershipEntity`. Die DB-Tabelle wird
-// aus der EntityDefinition über buildEntityTable abgeleitet, der
-// unique-Index ist via entity.indexes deklariert.
+// Single source of truth: `tenantMembershipEntity`. The database table is
+// derived from the EntityDefinition through buildEntityTable, and the
+// unique index is declared via entity.indexes.
 export const tenantMembershipEntity = createEntity({
   table: "read_tenant_memberships",
   fields: {

package/packages/bundled-features/src/tenant/schema/tenant.ts

@@ -21,9 +21,9 @@ export const tenantEntity = createEntity({
   description:
     "A tenant, the isolated workspace every other record belongs to, holding its key and display name, whether it is enabled, and its destruction-lifecycle state.",
   table: "read_tenants",
-  // tenant.id IS the tenantId-value that every other table references as FK.
-  // Alle tenantId-Spalten sind UUID (Migration 2026-04-16) → tenant.id muss
-  // UUID sein, sonst findet der tenants-Lookup nie. Default gen_random_uuid().
+  // `tenant.id` is the `tenantId` value referenced by every other table as a foreign key.
+  // Every `tenantId` column is UUID, so `tenant.id` must also be UUID; otherwise
+  // the tenant lookup never finds a match. The default is `gen_random_uuid()`.
   fields: {
     key: createTextField({
       required: true,
@@ -59,12 +59,10 @@ export const tenantEntity = createEntity({
     destroyStartedAt: createTimestampField({}),
     destroyedAt: createTimestampField({}),
   },
-  // tenant.key wird in Admin-URLs verwendet (`admin.<host>/<key>/...`) und
-  // muss eindeutig sein. Ohne unique-constraint hätte ein konkurrenter
-  // Self-Signup-Confirm einen TOCTOU-Race zwischen generateUniqueName-
-  // isAvailable-check und insert: zwei Tabs könnten sequentiell denselben
-  // Slug claimen, beide commits durch, der dritte User landet auf einem
-  // shared admin-URL-prefix.
+  // `tenant.key` appears in admin URLs (`admin.<host>/<key>/...`) and must be unique.
+  // Without a unique constraint, concurrent self-signup confirmation could pass
+  // the `generateUniqueName` `isAvailable` check before either insert, allowing
+  // two tabs to claim the same slug and causing users to share an admin URL prefix.
   indexes: [{ unique: true, columns: ["key"] }],
 });
 

package/packages/bundled-features/src/tenant/screens.ts

@@ -165,7 +165,7 @@ export function createMembersScreen(options?: {
 // feature.ts when `TenantFeatureOptions.inviteScreen` is set — see
 // createMembersScreen's doc comment above for why.
 export function createInviteCreateScreen(assignableAppRoles: AssignableAppRoles = new Map()) {
-  // Admin sees this screen too, so only app roles Admin may grant are offered (fw#2414).
+  // Admin sees this screen too, so only app roles Admin may grant are offered.
   const appRoleOptions = [...assignableAppRoles]
     .filter(([, assignableFrom]) => isAssignableByRole(assignableFrom, "Admin"))
     .map(([role]) => role);

package/packages/bundled-features/src/tenant/seeding.ts

@@ -76,12 +76,13 @@ export type SeedTenantMembershipOptions = {
 };
 
 export type SeedTenantOptions = {
-  /** Stable UUID — required for fixtures so the FE/BE können dieselbe ID
-   *  hardcoden (Sample-Switcher zeigt den Tenant beim Namen, der Test
-   *  prüft Memberships gegen exakt diese ID). Ohne ID müsste der Caller
-   *  den lookup-by-key extra machen. */
+  /**
+   * Stable UUID required for fixtures so the FE/BE can hardcode the same ID. The sample switcher
+   * displays the tenant by name, while tests verify memberships against this exact ID; without it,
+   * callers would need an extra lookup by key.
+   */
   readonly id: TenantId;
-  /** URL-/Slug-Form (z.B. "dev", "acme"). Indexed unique in der DB. */
+  /** URL/slug form (for example, "dev" or "acme"). Indexed unique in the database. */
   readonly key: string;
   /** Human-readable label (im Switcher angezeigt). */
   readonly name: string;
@@ -89,7 +90,7 @@ export type SeedTenantOptions = {
 };
 
 // seedTenant runs through the raw event-store executor, which fires no
-// postSave hooks (#1463) — feature-registered entity hooks on "tenant"
+// postSave hooks — feature-registered entity hooks on "tenant"
 // (e.g. tier-engine's auto-default-tier, an app's auto-default-compliance)
 // silently never run for tenants created this way. Pass `hooks` to fire
 // them explicitly, same lookup as the dispatcher (registry.getEntityPostSaveHooks
@@ -138,14 +139,14 @@ function buildSeedHookNotify(
 // registered entity/handler hooks fire (search-index/SSE system hooks are
 // wired at server-boot and out of reach here).
 //
-// Tenant re-scope (#1566): when `targetTenantId` is set we rebuild the
+// Tenant re-scope: when `targetTenantId` is set we rebuild the
 // tenant-bound pieces of the context (`_tenantId`, `db`, `notify`,
 // `hasFeature`, `user.tenantId`) — a shallow `{ ...ctx, _tenantId }` left
 // closures over the caller's tenant (self-signup is anonymous/system).
 // `query`/`write` bridges still share the caller's identity; hooks that
 // need a full identity switch use `writeAs`/`queryAs`.
 //
-// afterCommit (#1566): when `hooks.context.scheduleAfterCommit` is present
+// afterCommit: when `hooks.context.scheduleAfterCommit` is present
 // (HandlerContext from a live write), afterCommit hooks are queued onto the
 // dispatcher's sink and flush post-commit. Without a sink (fixture / plain
 // Connection) they still fire immediately — there is no outer TX to wait for.
@@ -255,20 +256,20 @@ export async function seedTenant(
   hooks?: SeedTenantHooks,
 ): Promise<{ id: TenantId }> {
   const by = options.by ?? TestUsers.systemAdmin;
-  // executor.create erwartet eine TenantDb (mit .insert()-API), nicht
-  // die rohe DbConnection. Auch wenn das Tenant-Aggregat selbst NICHT
-  // tenant-scoped ist, braucht der Wrap-Layer für die runtime-API zu
-  // existieren. by.tenantId reicht — keine Override-Semantik wie bei
-  // seedTenantMembership nötig.
+  // executor.create expects a TenantDb with an .insert()-API, not the raw
+  // DbConnection. Although the tenant aggregate is not tenant-scoped, the
+  // wrapper is required by the runtime API. by.tenantId is sufficient; unlike
+  // seedTenantMembership, no override semantics are needed.
   const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
 
   const existing = await fetchOne(db, tenantTable, { id: options.id });
   if (existing) return { id: options.id };
 
-  // Idempotenz: Aggregate kann im Event-Store existieren ohne Projection-Row
-  // (Projection-Drift nach rebuild, manuellem DELETE, oder async-lag). Wenn
-  // Stream-Version > 0 → kein create() — wäre version_conflict. Caller
-  // bekommt die ID, Projection wird beim nächsten Dispatcher-Cycle aufgebaut.
+  // Idempotency: the aggregate may exist in the event store without a
+  // projection row (projection drift after a rebuild, manual DELETE, or async
+  // lag). If the stream version is > 0, skip create() to avoid
+  // version_conflict. Return the ID; the next dispatcher cycle can rebuild the
+  // projection.
   const streamVersion = await getUnscopedAggregateStreamMaxVersion(db, options.id);
   if (streamVersion > 0) return { id: options.id };
 
@@ -311,7 +312,7 @@ export async function seedTenantMembership(
   db: DbRunner,
   options: SeedTenantMembershipOptions,
   // Optional, append-only — same rationale as seedTenant's hooks param
-  // (#1478): fires tenantMembership's postSave hooks (e.g. a Welcome-
+  // fires tenantMembership's postSave hooks (e.g. a Welcome-
   // notification or default-notification-preferences hook keyed off
   // `allOf: "tenantMembership"`) for fixtures/self-signup that opt in.
   // Omit to keep today's hook-less behavior.