@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/template-resolver/template-meta.js

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { HEX_COLOR_PATTERN, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./web/constants.js";
 import { MAIL_TONES } from "./web/mail-constants.js";
+import { MAIL_LAYOUT_ACCENT_LINES, MAIL_LAYOUT_BUTTON_STYLES, MAIL_LAYOUT_FONTS, MAIL_LAYOUT_WIDTHS, } from "./web/mail-layout-constants.js";
 // One or more kebab segments joined by ":" — notification templates are seeded
 // under their qualified name `feature:notify:name`.
 export const templateSlugSchema = z
@@ -66,12 +67,14 @@ const pdfMetaSchema = z
         .optional(),
 })
     .strict();
-const MAIL_LAYOUT_FONTS = ["sans", "serif"];
-const MAIL_LAYOUT_ACCENT_LINES = ["branding", "none"];
-const MAIL_LAYOUT_BUTTON_STYLES = ["filled-rounded", "filled-square", "outline"];
+const MAIL_LAYOUT_WIDTH_LITERALS = [
+    z.literal(MAIL_LAYOUT_WIDTHS[0]),
+    z.literal(MAIL_LAYOUT_WIDTHS[1]),
+    z.literal(MAIL_LAYOUT_WIDTHS[2]),
+];
 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/dist/template-resolver/template-preview.js

@@ -8,7 +8,7 @@ import * as z from "zod";
 import { createEmailAttachmentReader, createTemplateMailRenderer } from "../delivery/index.js";
 import { fileContextForTenant } from "../file-foundation/index.js";
 import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
-import { createTemplateResolverApi, TemplateNotFoundError } from "./api.js";
+import { createTemplateResolverApi, isRowDeliveredTo, TemplateNotFoundError, } from "./api.js";
 import { collectDocumentResourceKeys } from "./compile-document-body.js";
 import { parseStoredJson } from "./handlers/template-gates.js";
 import { validateTemplateDraft } from "./handlers/validate.query.js";
@@ -16,7 +16,7 @@ import { readLayoutRegions, sanitizeLayoutHtml, } from "./layout-regions.js";
 import { parseLinkedResourceEntries } from "./linked-resources.js";
 import { buildDisplayHtml } from "./preview-display-html.js";
 import { templateResourcesTable } from "./table.js";
-import { deliveryPolicyOf, isRowServedTo } from "./template-delivery-policy.js";
+import { deliveryPolicyOf } from "./template-delivery-policy.js";
 import { isMailTemplateMeta, parseTemplateMeta, readPdfTemplateMeta, } from "./template-meta.js";
 import { DEFAULT_MAIL_LAYOUT_SLUG, DEFAULT_PDF_LAYOUT_SLUG, MAIL_PREVIEW_MAX_BYTES, SYSTEM_TENANT_ID, } from "./web/constants.js";
 import { TemplateResolverErrors } from "./web/qualified-names.js";
@@ -149,7 +149,8 @@ export function estimateMailBytes(args) {
 async function loadEditedRowResources(ctx, user, input) {
     const rows = await selectMany(ctx.db, templateResourcesTable, { tenantId: user.tenantId, slug: input.slug, kind: "mail", locale: input.locale }, { 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/dist/template-resolver/web/client-plugin.js

@@ -107,7 +107,7 @@ function makeTreeProvider(tenantIdOverride, collectionId) {
         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,
@@ -224,7 +224,7 @@ function TextBlockEditor({ target, }) {
     const [savedMsg, setSavedMsg] = useState(null);
     // 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;

package/dist/template-resolver/web/constants.d.ts

@@ -10,7 +10,7 @@ export declare const UPSERT_KINDS: readonly ["mail", "document-pdf", "image-snap
 export type UpsertKind = (typeof UPSERT_KINDS)[number];
 export declare const TEXT_BLOCK_KIND: "text-block";
 export declare const COLLECTION_REFUSED_KINDS: readonly ["mail", "mail-layout", "pdf-layout"];
-export declare function isCollectionRefusedKind(kind: string): boolean;
+export declare function isCollectionRefusedKind(kind: unknown): kind is (typeof COLLECTION_REFUSED_KINDS)[number];
 export declare const CONTENT_FORMATS: readonly ["markdown", "mjml", "html", "plain"];
 export type ContentFormat = (typeof CONTENT_FORMATS)[number];
 export declare const TEMPLATE_SCOPES: readonly ["system", "tenant"];
@@ -18,8 +18,8 @@ export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
 export declare const TEMPLATE_STATUSES: readonly ["draft", "active", "archived"];
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
 export declare const ACTIVE_TEMPLATE_STATUS = "active";
+export { HEX_COLOR_PATTERN } from "./mail-layout-constants.ts";
 export { PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, type PdfOrientation, type PdfPageFormat, } from "./pdf-constants.ts";
-export declare const HEX_COLOR_PATTERN: RegExp;
 export declare const DEFAULT_MAIL_LAYOUT_SLUG = "default";
 export declare const DEFAULT_PDF_LAYOUT_SLUG = "default";
 export declare const MAIL_PREVIEW_MAX_BYTES: number;

package/dist/template-resolver/web/constants.js

@@ -4,6 +4,7 @@
 // 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"];
 // Kinds whose html body is a rich document: the server rebuilds it through the
 // document schema on every write (see document-sanitizer.ts).
@@ -44,15 +45,14 @@ export const COLLECTION_REFUSED_KINDS = [
     "pdf-layout",
 ];
 export function isCollectionRefusedKind(kind) {
-    return COLLECTION_REFUSED_KINDS.some((refused) => refused === kind);
+    return isOneOf(COLLECTION_REFUSED_KINDS, kind);
 }
 export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"];
 export const TEMPLATE_SCOPES = ["system", "tenant"];
 export const TEMPLATE_STATUSES = ["draft", "active", "archived"];
 export const ACTIVE_TEMPLATE_STATUS = "active";
+export { HEX_COLOR_PATTERN } from "./mail-layout-constants.js";
 export { PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./pdf-constants.js";
-// 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";
 // The mail transport enforces no size limit of its own; 10 MiB is a common provider ceiling.

package/dist/template-resolver/web/index.d.ts

@@ -2,6 +2,7 @@ export { textBlocksClient } from "./client-plugin.tsx";
 export { DocumentContentEditor } from "./document-editor.tsx";
 export { type DocumentEditorChrome, type DocumentEditorHandle, type DocumentEditorProps, type DocumentResourcePreview, type DocumentToolbarBlock, MAIL_DOCUMENT_BLOCKS, 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, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./pdf-constants.ts";
 export { PlaceholderLineEditor, type PlaceholderLineEditorProps, } from "./placeholder-line-editor-lazy.tsx";
 export { TemplateResolverErrors, TemplateResolverHandlers, TemplateResolverQueries, } from "./qualified-names.ts";

package/dist/template-resolver/web/index.js

@@ -7,6 +7,7 @@ export { textBlocksClient } from "./client-plugin.js";
 export { DocumentContentEditor } from "./document-editor.js";
 export { MAIL_DOCUMENT_BLOCKS, PDF_DOCUMENT_BLOCKS, } from "./document-toolbar-blocks.js";
 export { MAIL_TONES } from "./mail-constants.js";
+export { HEX_COLOR_PATTERN, MAIL_LAYOUT_ACCENT_LINES, MAIL_LAYOUT_BUTTON_STYLES, MAIL_LAYOUT_FONTS, MAIL_LAYOUT_WIDTHS, } from "./mail-layout-constants.js";
 export { PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./pdf-constants.js";
 export { PlaceholderLineEditor, } from "./placeholder-line-editor-lazy.js";
 export { TemplateResolverErrors, TemplateResolverHandlers, TemplateResolverQueries, } from "./qualified-names.js";

package/dist/template-resolver/web/mail-layout-constants.d.ts

@@ -0,0 +1,5 @@
+export declare const MAIL_LAYOUT_WIDTHS: readonly [560, 600, 640];
+export declare const MAIL_LAYOUT_FONTS: readonly ["sans", "serif"];
+export declare const MAIL_LAYOUT_ACCENT_LINES: readonly ["branding", "none"];
+export declare const MAIL_LAYOUT_BUTTON_STYLES: readonly ["filled-rounded", "filled-square", "outline"];
+export declare const HEX_COLOR_PATTERN: RegExp;

package/dist/template-resolver/web/mail-layout-constants.js

@@ -0,0 +1,7 @@
+// 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];
+export const MAIL_LAYOUT_FONTS = ["sans", "serif"];
+export const MAIL_LAYOUT_ACCENT_LINES = ["branding", "none"];
+export const MAIL_LAYOUT_BUTTON_STYLES = ["filled-rounded", "filled-square", "outline"];
+// 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/dist/tenant/feature.js

@@ -54,10 +54,10 @@ export function createTenantFeature(options) {
         r.entity({ name: "tenant-invitation", ...tenantInvitationEntity });
         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: [
@@ -79,16 +79,16 @@ export function createTenantFeature(options) {
                     default: "de",
                     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,
                     read: access.systemAdmin,
                     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/dist/tenant/handlers/member-directory.query.d.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 export declare const memberDirectoryQuery: import("@cosmicdrift/kumiko-framework/engine").PagedQueryHandlerDefinition<"memberDirectory", z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>, {
     id: string;
     label: string;

package/dist/tenant/handlers/member-directory.query.js

@@ -22,7 +22,7 @@ async function loadMemberUserIds(db, tenantId) {
     const memberships = await selectMany(db, tenantMembershipsTable, { tenantId });
     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:
@@ -40,6 +40,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: "Lists users as id/label pairs for resolving user references to display names: the caller's own tenant members for an admin, every user for a SystemAdmin; carries no email or role data.",
@@ -50,21 +52,26 @@ export const memberDirectoryQuery = definePagedQueryHandler({
                 message: "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;
         let users;
         if (isSystemAdmin(query.user)) {
             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(db, userTable, { id: [...userIds] }, {

package/dist/tenant/handlers/members.query.js

@@ -16,7 +16,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/dist/tenant/handlers/team-list.query.js

@@ -38,7 +38,7 @@ function compareTeamRows(a, b, field, dir) {
     const bv = field === "email" ? (b.email ?? "") : b.status;
     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/dist/tenant/handlers/tenant-directory.query.d.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 export declare const tenantDirectoryQuery: import("@cosmicdrift/kumiko-framework/engine").PagedQueryHandlerDefinition<"tenantDirectory", z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>, {
     id: string;
     label: string;

package/dist/tenant/handlers/tenant-directory.query.js

@@ -5,7 +5,7 @@ import * as z from "zod";
 import { decryptTenantNames, takeTenantsMatchingDecryptedName } from "../decrypt-tenant-names.js";
 import { tenantTable } from "../schema/tenant.js";
 import { isSystemAdmin } from "./is-system-admin.js";
-// 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
@@ -21,9 +21,11 @@ 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.",
+    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. 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) {
@@ -31,12 +33,14 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
                 message: "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;
         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" },
@@ -47,7 +51,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/dist/tenant/invitation-table.js

@@ -1,44 +1,42 @@
-// 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 { createEntity, createMultiSelectField, createNumberField, createSelectField, createTextField, createTimestampField, } from "@cosmicdrift/kumiko-framework/engine";
 // kumiko-lint-ignore cross-feature-import global-role options are owned by the user feature
 import { GLOBAL_ROLE_OPTIONS } from "../user/web/constants.js";
-// 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",
     cancelled: "cancelled",
     expired: "expired",
 };
-// 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,
@@ -48,11 +46,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,
@@ -73,11 +71,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" },
@@ -91,11 +89,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/dist/tenant/membership-table.js

@@ -11,9 +11,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/dist/tenant/schema/tenant.js

@@ -10,9 +10,9 @@ export const TENANT_LIFECYCLE_STATUSES = [
 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,
@@ -48,12 +48,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"] }],
 });
 export const tenantTable = buildEntityTable("tenant", tenantEntity);

package/dist/tenant/screens.js

@@ -141,7 +141,7 @@ export function createMembersScreen(options) {
 // feature.ts when `TenantFeatureOptions.inviteScreen` is set — see
 // createMembersScreen's doc comment above for why.
 export function createInviteCreateScreen(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/dist/tenant/seeding.d.ts

@@ -14,12 +14,13 @@ export type SeedTenantMembershipOptions = {
     readonly by?: SessionUser;
 };
 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;

package/dist/tenant/seeding.js

@@ -69,14 +69,14 @@ function buildSeedHookNotify(context, scopedUser, targetTenantId, notifyTiming)
 // 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.
@@ -161,19 +161,19 @@ target) {
  */
 export async function seedTenant(db, options, hooks) {
     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 };
@@ -206,7 +206,7 @@ export async function seedTenant(db, options, hooks) {
  */
 export async function seedTenantMembership(db, options, 
 // 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.

package/dist/tenant/testing.js

@@ -1,7 +1,6 @@
-// /testing re-exportiert /seeding. Ehemalige Heimat der seed-Helpers,
-// jetzt nur noch Aggregation. Die Helpers leben in `/seeding` weil sie
-// genauso vom Dev-Server-Bootstrap (runDevApp) konsumiert werden — nicht
-// nur von Tests. Vertrag der Helpers ist stabil, test-spezifische
-// Knöpfe gehören NICHT hier rein (würde dev-boots brechen wenn jemand
-// einen lockout-test-Knopf einbaut).
+// `/testing` re-exports `/seeding`; it is no longer the home of the seed helpers.
+// The helpers live in `/seeding` because they are also consumed by the
+// development-server bootstrap (`runDevApp`), not only by tests. Keep their
+// stable contract here; test-specific options do not belong in this module,
+// because they could break development boots when a lockout-test option is added.
 export * from "./seeding.js";