@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts

@@ -1,35 +1,34 @@
-// verifyAndParseStripeWebhook — Stripe-spezifische sig-verify +
-// event-mapping. Wird vom Plugin-Build (feature.ts) als
-// `verifyAndParseWebhook` registriert.
+// verifyAndParseStripeWebhook — Stripe-specific signature verification +
+// event mapping. Registered by the plugin build (feature.ts) as
+// `verifyAndParseWebhook`.
 //
 // **Steps:**
-//   1. Sig-verify via stripe.webhooks.constructEvent (HMAC-SHA-256
-//      gegen rawBody + Stripe-Signature-Header). Wirft bei mismatch
-//      oder älter als 5min (Replay-Protection).
+//   1. Verify the signature via stripe.webhooks.constructEvent (HMAC-SHA-256
+//      against rawBody + Stripe-Signature header). Throws on mismatch or
+//      timestamps older than 5 minutes (replay protection).
 //   1b. checkout.session.completed / .async_payment_succeeded branch off
 //       here into a PaymentEvent (one-off-payment, own aggregate) — see
-//       "One-off-payment" section below. Everything else falls through.
-//   2. Event-type-Filter: nur die 5 event-types die wir auf
-//      SubscriptionEventTypes mappen kommen weiter; alles andere
-//      returnt null (foundation antwortet 200 ignored).
-//   3. Stripe-payload → SubscriptionEvent normalisieren
-//      (status-mapping, tenant-id aus metadata, price-to-tier-Lookup).
+//       the "One-off-payment" section below. Everything else falls through.
+//   2. Event-type filter: only the 5 event types mapped to
+//      SubscriptionEventTypes continue; everything else returns null
+//      (the foundation responds with 200 ignored).
+//   3. Normalize the Stripe payload into a SubscriptionEvent
+//      (status mapping, tenant ID from metadata, price-to-tier lookup).
 //
-// **Runtime-keys (pre-tenant):** api-key + webhook-secret kommen NICHT
-// mehr aus einem mount-time-Closure, sondern werden zur Webhook-Zeit aus
-// dem `StripeWebhookRuntime` aufgelöst. Der foundation-webhook-handler
-// reicht einen system-scoped SecretsContext als 3. Arg durch; der runtime
-// liest beide Keys daraus (un-audited, system-internal) mit Fallback auf
-// die factory-options. Damit rotiert ein Key ohne Redeploy — und der
-// invoice-lazy-fetch (unten) nutzt denselben rotierten Client wie der
-// sig-verify, kein split-brain.
+// **Runtime keys (pre-tenant):** the API key and webhook secret no longer
+// come from a mount-time closure; they are resolved from `StripeWebhookRuntime`
+// at webhook time. The foundation webhook handler passes a system-scoped
+// SecretsContext as the third argument; the runtime reads both keys from it
+// (unaudited, system-internal), falling back to the factory options. This
+// allows key rotation without a redeploy, and the invoice lazy-fetch below
+// uses the same rotated client as signature verification, avoiding split-brain.
 //
 // **Invoice-event lazy-fetch:**
-// Invoice payloads carry only the subscription id (Stripe does not expand
-// subscription in webhooks), so the plugin lazy-fetches via
+// Invoice payloads carry only the subscription ID (Stripe does not expand
+// subscriptions in webhooks), so the plugin lazy-fetches via
 // `stripe.subscriptions.retrieve(subId)` to get the full subscription for
 // status/tier/period-end mapping. resource_missing (deleted between webhook
-// and retrieve) returns null; any other Stripe error becomes 503 so Stripe
+// and retrieval) returns null; any other Stripe error becomes 503 so Stripe
 // redelivers.
 
 import type {
@@ -77,18 +76,18 @@ function transientProviderRejection(error: unknown): ExtraRouteRejection {
 // =============================================================================
 
 export type StripeWebhookOptions = {
-  /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
-   *  mapped auf tier-name. Fehlt die price-id im Mapping → null. App-
-   *  spezifisch, bleibt eine factory-option (kein Secret). */
+  /** Price-to-tier map. The plugin reads the price ID from the event and
+   *  maps it to a tier name. Returns null when the price ID is not mapped.
+   *  App-specific and remains a factory option, not a secret. */
   readonly priceToTier: Readonly<Record<string, string>>;
 };
 
 /**
- * Stripe-webhook-handler. Implementiert den Plugin-Contract
- * `verifyAndParseWebhook`. **Pre-tenant-resolution** — kein
- * HandlerContext; statt eines mount-time-Clients löst der `runtime` den
- * Stripe-Client + das webhook-secret zur Call-Zeit aus dem optionalen
- * system-SecretsContext (3. Arg) auf.
+ * Stripe webhook handler implementing the plugin contract
+ * `verifyAndParseWebhook`. **Pre-tenant resolution** — there is no
+ * HandlerContext; instead of using a mount-time client, `runtime` resolves
+ * the Stripe client and webhook secret at call time from the optional
+ * system SecretsContext (third argument).
  */
 export function verifyAndParseStripeWebhook(
   runtime: StripeWebhookRuntime,
@@ -104,16 +103,16 @@ export function verifyAndParseStripeWebhook(
       throw new Error("subscription-stripe: stripe-signature header missing");
     }
 
-    // 0. Runtime-resolve: api-key (für client + lazy-fetch) + webhook-
-    //    secret (für sig-verify) aus system-secrets, Fallback factory-
-    //    options. Wirft wenn beide unkonfiguriert.
+    // 0. Resolve at runtime: obtain the API key (for the client and lazy fetch)
+    //    and webhook secret (for signature verification) from system secrets,
+    //    falling back to the factory options. Throws if neither is configured.
     const { stripe, webhookSecret } = await runtime.resolve(systemSecrets);
 
-    // 1. Sig-verify. constructEvent throws bei mismatch (= invalid sig)
-    //    oder timestamp-tolerance-violation (default 5min). Foundation
-    //    mapped throw → HTTP 401. Applies to BOTH branches below — the
-    //    payment-branch only branches off AFTER this check; there's no
-    //    path that bypasses signature verification.
+    // 1. Verify the signature. constructEvent throws on a mismatch (invalid
+    //    signature) or timestamp-tolerance violation (default: 5 minutes).
+    //    The foundation maps the thrown error to HTTP 401. This applies to
+    //    BOTH branches below: the payment branch is selected only AFTER this
+    //    check, so no path bypasses signature verification.
     let event: Stripe.Event;
     try {
       event = await stripe.webhooks.constructEventAsync(rawBody, sigHeader, webhookSecret);
@@ -131,30 +130,29 @@ export function verifyAndParseStripeWebhook(
       return await parsePaymentEvent(event, stripe);
     }
 
-    // 2. Event-type-Filter — wir kennen nur 5.
+    // 2. Event-type filter — only 5 event types are supported.
     const normalizedType = mapStripeEventType(event.type);
     if (!normalizedType) {
       return null; // foundation returnt 200 ignored
     }
 
-    // 3. Payload-extraction. Stripe liefert je nach event.type
-    //    verschiedene data.object-shapes. Wir extrahieren die
-    //    Subscription-Daten — entweder direkt (subscription-events)
-    //    oder via lazy-fetch (invoice-events).
+    // 3. Extract the payload. Stripe uses different data.object shapes
+    //    depending on event.type. Extract subscription data either directly
+    //    (subscription events) or through a lazy fetch (invoice events).
     const sub = await extractSubscriptionFromEvent(event, stripe);
     if (!sub) {
-      // event-type war unter den 5 (oben gefiltert), aber payload-shape
-      // matched nicht — Stripe-SDK-Schema-Drift, defensive null.
+      // The event type passed the 5-item filter, but its payload shape did not
+      // match — treat this as Stripe SDK schema drift and return null defensively.
       return null;
     }
 
-    // 4. Tenant-resolution aus metadata. App-Builder setzt
-    //    `metadata.tenantId` beim createCheckoutSession-call.
+    // 4. Resolve the tenant from metadata. The app builder sets
+    //    `metadata.tenantId` when calling createCheckoutSession.
     const tenantId = sub.metadata?.["tenantId"];
     if (!tenantId || tenantId.length === 0) {
-      // Subscription ohne tenant-metadata → kann kein subscription
-      // erstellen ohne tenant-resolution. Drop the event silent
-      // (foundation 200 ignored). App-Owner-Bug, nicht foundation-Bug.
+      // A subscription without tenant metadata cannot be created without tenant
+      // resolution. Drop the event silently (the foundation responds with 200
+      // ignored). This is an app-owner error, not a foundation error.
       return null;
     }
 
@@ -218,7 +216,7 @@ export function mapStripeSubscriptionState(
   const periodEndUnixSec = sub.items.data[0]?.current_period_end ?? 0;
   // Stripe returns Unix-seconds; Temporal.Instant.fromEpochMilliseconds
   // expects ms. Multiply, then ISO. (No-Date-API-Guard forbids
-  // `new Date()` — static import above, not the ambient global, see #1490.)
+  // `new Date()` — static import above, not the ambient global.)
   const currentPeriodEnd = Temporal.Instant.fromEpochMilliseconds(
     periodEndUnixSec * 1000,
   ).toString();
@@ -264,9 +262,9 @@ export function mapStripeEventType(stripeType: string): SubscriptionEventType |
   }
 }
 
-/** Stripe-status → normalisiert. Defensive: unbekannte Status →
- *  incomplete (Plugin sollte das nicht erreichen, aber wir wollen
- *  kein ungültiger status-string in der DB). */
+/** Maps Stripe statuses to normalized statuses. Unknown statuses are
+ *  mapped defensively to incomplete; the plugin should not receive them, but
+ *  an invalid status string must not be stored in the database. */
 export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): SubscriptionStatus {
   switch (stripeStatus) {
     case "active":
@@ -293,9 +291,9 @@ export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): Subsc
   }
 }
 
-/** Holt die Subscription aus dem Event. Subscription-events haben sie
- *  direkt im data.object; invoice-events haben nur die subscription-id
- *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve. */
+/** Gets the subscription from the event. Subscription events include it
+ *  directly in data.object; invoice events include only the subscription ID
+ *  and require a lazy fetch via stripe.subscriptions.retrieve. */
 // @wrapper-known semantic-alias
 async function extractSubscriptionFromEvent(
   event: Stripe.Event,
@@ -308,16 +306,16 @@ async function extractSubscriptionFromEvent(
       return event.data.object as Stripe.Subscription; // @cast-boundary engine-bridge
     case StripeEventTypes.invoicePaid:
     case StripeEventTypes.invoicePaymentFailed: {
-      // Lazy-fetch der subscription. invoice.subscription ist eine
-      // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
-      // full subscription-Object damit der downstream-mapping
-      // (status, tier via priceId, period-end) konsistent funktioniert.
+      // Lazy-fetch the subscription. invoice.subscription is a string ID because
+      // Stripe webhooks do not expand it automatically. Fetch the full
+      // subscription so downstream status, tier via priceId, and period-end
+      // mapping remain consistent.
       const invoice = event.data.object as Stripe.Invoice; // @cast-boundary engine-bridge
       const subRef = (invoice as { subscription?: string | Stripe.Subscription | null }) // @cast-boundary engine-payload
         .subscription;
       if (!subRef) {
-        // Invoice ohne subscription-reference (= one-shot-invoice, nicht
-        // recurring). Nicht unsere Domain — ignorieren.
+        // An invoice without a subscription reference is a one-shot invoice, not a
+        // recurring invoice. It is outside this domain and should be ignored.
         return null;
       }
       const subId = typeof subRef === "string" ? subRef : subRef.id;

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

@@ -150,9 +150,9 @@ export type TagsFeatureOptions = {
   /** Row-level ownership on the tag-assignment rows themselves — orthogonal to
    *  `access`, which only gates whether a caller may dispatch assign/remove/list
    *  at all. `ownership.read` is no longer what keeps a caller from reading
-   *  assignments on host entities they can't see: that gate is default-on since
-   *  fw#2766 and derives from the entity's `parentRef`. Use `ownership.read` for
-   *  an ADDITIONAL row rule on the assignment row itself; it is AND-ed with the
+   *  assignments on host entities they can't see: that gate is default-on and
+   *  derives from the entity's `parentRef`. Use `ownership.read` for an
+   *  ADDITIONAL row rule on the assignment row itself; it is AND-ed with the
    *  host-visibility gate, never a replacement for it. Applies only to
    *  `tag-assignment`; the `tag` catalog stays tenant-wide by design.
    *

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

@@ -6,7 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { DEFAULT_TAG_ACCESS, TAGS_EDIT_SCREEN_ID, TAGS_SCREEN_ID } from "./web/constants.ts";
 
-// Declarative catalog screens (Phase-3 / #2312). Access matches create/update/
+// Declarative catalog screens. Access matches create/update/
 // delete so createTagsFeature({ access|roles }) stays consistent. TagManager
 // remains for TagPicker/TagSection — only the standalone admin screen moved.
 

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

@@ -232,20 +232,20 @@ async function fetchTemplate(
     { limit: 1 },
   );
   // @cast-boundary db-row — db.select returnt unbenanntes unknown[],
-  // Row-Shape ist via templateResourcesTable + buildBaseColumns garantiert.
+  // The row shape is guaranteed by templateResourcesTable + buildBaseColumns.
   return (rows[0] as TemplateResourceRow | undefined) ?? null;
 }
 
 function toPublic(row: TemplateResourceRow): TemplateResource {
   // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
-  // scope/status als generic text. CHECK-Constraints in der DB schränken
-  // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
+  // scope/status as generic text. Database CHECK constraints restrict
+  // them to the union types; the cast asserts that schema knowledge.
   const kind = row.kind as TemplateKind;
-  // @cast-boundary db-row — siehe kind.
+  // @cast-boundary db-row — see kind.
   const contentFormat = row.contentFormat as ContentFormat;
-  // @cast-boundary db-row — siehe kind.
+  // @cast-boundary db-row — see kind.
   const scope = row.scope as "system" | "tenant";
-  // @cast-boundary db-row — siehe kind.
+  // @cast-boundary db-row — see kind.
   const status = row.status as "draft" | "active" | "archived";
   const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
   return {
@@ -286,7 +286,7 @@ function parseJson(raw: string | null): Record<string, unknown> {
   try {
     const parsed = JSON.parse(raw);
     // @cast-boundary engine-payload — JSON.parse returnt unknown, typeof-Guard
-    // grenzt auf object ein; Record<string, unknown> ist der minimale common-shape.
+    // narrows it to object; Record<string, unknown> is the minimal common shape.
     return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
   } catch {
     return {};
@@ -302,14 +302,14 @@ export class TemplateNotFoundError extends Error {
   }
 }
 
-// Single point of truth für "dieser Handler braucht template-resolver".
-// Pattern symmetrisch zu requireTextContent.
+// Single source of truth for "this handler requires template-resolver".
+// Pattern symmetric with requireTextContent.
 export function requireTemplateResolver(
   ctx: { readonly templateResolver?: TemplateResolverApi } | object,
   callerName: string,
 ): TemplateResolverApi {
   // @cast-boundary engine-bridge — templateResolver kommt per extraContext
-  // aus App-Bootstrap, Framework-Container kennt das Feld nicht von sich aus.
+  // from App-Bootstrap; the framework container does not know this field on its own.
   const api = (ctx as { templateResolver?: TemplateResolverApi }).templateResolver;
   if (!api) {
     throw new InternalError({

package/packages/bundled-features/src/template-resolver/handlers/find-by-id.query.ts

@@ -6,11 +6,11 @@ import { deliveryPolicyOf, isRowServedTo } from "../template-delivery-policy.ts"
 import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow } from "../template-draft.ts";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.ts";
 
-// Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
-// archived Status. Tenant-Isolation: User sieht nur Templates des
-// eigenen Tenants oder SYSTEM_TENANT (system-defaults sind public-
-// readable); ctx.db is tenant-scoped for every role, so the check below is defense in depth. Anonymous bleibt aus — Public-
-// Read geht über resolveTemplate aus der API, nicht hier.
+// Admin lookup for the UI editing flow. Returns the raw template, including draft/
+// archived status. Tenant isolation: users see only templates belonging to their own
+// tenant or SYSTEM_TENANT (system defaults are publicly readable); ctx.db is tenant-
+// scoped for every role, so the check below is defense in depth. Anonymous access is
+// excluded—public reads go through resolveTemplate in the API, not here.
 export const findByIdQuery = defineQueryHandler({
   name: "find-by-id",
   schema: z.object({ id: z.string().min(1) }),

package/packages/bundled-features/src/template-resolver/handlers/list.query.ts

@@ -40,7 +40,7 @@ export const listQuery = defineQueryHandler({
       where["status"] = query.payload.status;
     }
 
-    // @cast-boundary db-row — selectMany returnt unknown[]; Row-Shape ist
+    // @cast-boundary db-row — selectMany returns unknown[]; Row shape is
     // durch templateResourcesTable + buildBaseColumns garantiert.
     const rows = (await selectMany(ctx.db, templateResourcesTable, where, {
       limit: 500,

package/packages/bundled-features/src/template-resolver/handlers/shared.ts

@@ -38,8 +38,8 @@ export const titleSchema = z.string().min(1).max(200);
 export const contentFormatSchema = z.enum(CONTENT_FORMATS);
 export const statusSchema = z.enum(TEMPLATE_STATUSES);
 
-// Common Upsert-Payload — geteilt zwischen upsertSystem + upsertTenant.
-// Unterschied: ACL + tenantId-Bestimmung, sonst identisch.
+// Common upsert payload shared by upsertSystem and upsertTenant.
+// Only ACL and tenantId determination differ.
 export const upsertPayloadSchema = z.object({
   slug: templateSlugSchema,
   kind: kindSchema,

package/packages/bundled-features/src/template-resolver/handlers/template-write.ts

@@ -258,9 +258,9 @@ export async function writeTemplateRow(
     { streamTenantId },
   );
   if (!result.isSuccess) return result;
-  // @cast-boundary db-row — executor.create returnt Record-row aus
-  // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-  // Returning-Klausel ist.
+  // @cast-boundary db-row — executor.create returns a row from
+  // INSERT RETURNING; the { id } shape is guaranteed because the primary key is in the
+  // RETURNING clause.
   const createdRow = result.data as { id: string | number };
   return {
     isSuccess: true,

package/packages/bundled-features/src/template-resolver/handlers/upsert-system.write.ts

@@ -3,10 +3,9 @@ import { resolveTemplateVariables } from "../template-validation.ts";
 import { upsertPayloadSchema } from "./shared.ts";
 import { writeTemplateRow } from "./template-write.ts";
 
-// System-Template anlegen/updaten. Liegt unter SYSTEM_TENANT_ID,
-// scope='system'. Nur SystemAdmin (globale Rolle). TenantAdmin kann
-// keine System-Defaults überschreiben — der nutzt upsertTenant für
-// Overrides.
+// Creates or updates a system template under SYSTEM_TENANT_ID with
+// scope='system'. Only SystemAdmin can change these global defaults;
+// TenantAdmin uses upsertTenant for overrides instead.
 export const upsertSystemWrite = defineWriteHandler({
   name: "upsert-system",
   schema: upsertPayloadSchema,

package/packages/bundled-features/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -9,11 +9,10 @@ import { resolveTemplateVariables } from "../template-validation.ts";
 import { upsertPayloadSchema } from "./shared.ts";
 import { writeTemplateRow } from "./template-write.ts";
 
-// Tenant-Override anlegen/updaten. Liegt unter event.user.tenantId,
-// scope='tenant'. Default-Status='draft' — User publisht explizit
-// via publish-Handler. SystemAdmin kann via tenantIdOverride für
-// einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
-// Tenant-Templates kuratiert).
+// Creates or updates a tenant override under event.user.tenantId with scope='tenant'.
+// The default status is 'draft'; users must publish explicitly via the publish handler.
+// SystemAdmin can write for another tenant through tenantIdOverride, typically to
+// curate tenant templates from a platform admin UI.
 export function makeUpsertTenantWrite(policy: TemplateEditPolicy) {
   return defineWriteHandler({
     name: "upsert-tenant",

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

@@ -29,7 +29,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/event-store";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { executor } from "./handlers/shared.ts";
 import { evaluateTemplateWrite } from "./handlers/template-gates.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
@@ -232,11 +232,11 @@ export async function seedSystemTemplate(
         }
         throw new Error(`seedSystemTemplate create failed: ${JSON.stringify(result)}`);
       }
-      const data = result.data as Partial<TemplateResourceRow>;
-      if (data.id === undefined) {
+      const createdId = propertyOf(result.data, "id");
+      if (createdId === undefined) {
         throw new Error("seedSystemTemplate: executor.create did not return an id");
       }
-      return { id: String(data.id) };
+      return { id: String(createdId) };
     },
     update: (row) => applyUpdate(row, existingRow),
   });

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

@@ -23,16 +23,15 @@ const renameMailHtmlKind: EntityEventMigration = {
   transform: (fields) => (fields["kind"] === "mail-html" ? { ...fields, kind: "mail" } : fields),
 };
 
-// TemplateResource — strukturierte Template-Definition mit Tenant-
-// Override-Hierarchie, Locale-Fallback und Resource-Linking via
-// file-foundation. Pro (tenantId, slug, kind, locale) genau eine Row;
-// scope/status/version differenzieren Lifecycle. Der Entwurf neben einer
-// aktiven Fassung liegt in `draft`; die Hauptfelder bleiben die ausgelieferte
-// Fassung.
+// TemplateResource — structured template definition with tenant override
+// hierarchy, locale fallback, and resource linking via file-foundation. Exactly
+// one row per (tenantId, slug, kind, locale); scope/status/version distinguish
+// lifecycle states. The draft alongside an active revision is stored in `draft`;
+// the main fields remain the served revision.
 //
-// `variableSchema` + `linkedResources` sind JSON-Strings in longText
-// (Pattern aus compliance-profiles — kein dedizierter jsonbField im
-// createEntity-DSL). App-Layer parsed JSON, persistiert wieder als String.
+// `variableSchema` + `linkedResources` are JSON strings in longText
+// (following compliance-profiles because the createEntity DSL has no dedicated
+// jsonbField). The application layer parses the JSON and persists it as a string.
 export const templateResourceEntity = createEntity({
   table: "read_template_resources",
   fields: {
@@ -47,8 +46,8 @@ export const templateResourceEntity = createEntity({
     // Folder path for the content tree, `/`-separated ("page/marketing").
     // null = root node.
     folder: createTextField({ personal: false, reason: "technical_reference" }),
-    // Template-body is authored by TenantAdmin/Operator (email-templates etc.),
-    // business data — kein end-user UGC.
+    // Template body is authored by TenantAdmin/Operator (email-templates, etc.),
+    // and is business data—not end-user UGC.
     content: createLongTextField({
       personal: false,
       reason: "is_business_data",
@@ -90,9 +89,9 @@ export type EntityAuditColumns = {
   readonly modifiedById: string | null;
 };
 
-// Concrete Row-Type — single-source dafür dass die unknown-Werte die
-// Drizzle aus `Record<string, unknown>` liefert genau einmal benannt
-// werden (statt 12× `row["x"] as Y` Casts in Handlern + Resolver).
+// Concrete row type—the single source of truth for naming the unknown values
+// returned by Drizzle from `Record<string, unknown>` (instead of 12×
+// `row["x"] as Y` casts in handlers and resolvers).
 export type TemplateResourceRow = {
   readonly id: string | number;
   readonly version: number;

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/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:

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