@cosmicdrift/kumiko-samples 0.386.0 → 0.387.0

package/packages/bundled-features/src/channel-email/smtp-transport.ts

@@ -1,37 +1,39 @@
-// SMTP-Transport für EmailTransport-Interface. nodemailer-basiert
-// (battle-tested, TLS-AUTH-Pool-Reconnect handled). Universaler default
-// für apps die keinen Vendor-spezifischen Sender wollen — funktioniert
-// gegen jeden SMTP-Server (Gmail, eigener Postfix, Brevo-SMTP-relay,
-// Office 365, Mailhog für lokales testing).
+// SMTP transport for the EmailTransport interface, based on nodemailer
+// (battle-tested, handles TLS, auth and pool reconnects). It is the universal
+// default for apps that do not need a vendor-specific sender and works with
+// any SMTP server (Gmail, a private
+// Postfix server, a Brevo SMTP relay, Office 365, or Mailhog for local
+// testing).
 //
-// Why SMTP statt Vendor-API als default:
-//   1. EU-Story: kein Daten an US-Vendor, App-Owner wählt Server.
-//   2. Self-Hosting: Customer kann eigenen Mailserver nutzen, kein
+// Why SMTP instead of a vendor API as the default:
+//   1. EU data control: the app owner chooses the server instead of sending
+//      data to a US vendor.
+//   2. Self-hosting: customers can use their own mail server without an
 //      external account.
-//   3. Universalität: jeder Vendor (Brevo, Resend, Mailgun, Postmark)
-//      bietet auch SMTP — wer Brevo will, setzt Brevos SMTP-Credentials.
+//   3. Universality: every vendor (Brevo, Resend, Mailgun, Postmark) also
+//      offers SMTP, so Brevo users can provide Brevo SMTP credentials.
 //
-// Transport-Pool: nodemailer.createTransport({pool: true}) hält bis zu
-// 5 Verbindungen offen + reused. Bei kleinen Apps reicht das; für High-
-// Volume-Apps muss der Caller eine eigene Implementation mit
-// dedizierter Queue (BullMQ + retry) drüberlegen.
+// The transport pool (createTransport({ pool: true })) keeps up to 5
+// connections open and reuses them. That is enough for small apps; for
+// high-volume apps the caller must layer its own implementation with a
+// dedicated queue (BullMQ + retry) on top.
 
 import { createTransport, type Transporter } from "nodemailer";
 import addressparser from "nodemailer/lib/addressparser";
 import type { EmailAttachment, EmailMessage, EmailTransport } from "./types.ts";
 
 export type SmtpTransportOptions = {
-  /** SMTP-Server-Host (z.B. "smtp.gmail.com", "in-v3.mailjet.com",
-   *  "localhost" für Mailhog/MailCatcher in dev). */
+  /** SMTP server host (for example, "smtp.gmail.com", "in-v3.mailjet.com",
+   *  or "localhost" for Mailhog/MailCatcher in development). */
   readonly host: string;
-  /** Default 587 (STARTTLS). 465 für implicit-TLS, 25 für unencrypted
-   *  (nur lokal/intern, nie public). */
+  /** Default 587 (STARTTLS). 465 uses implicit TLS; 25 is unencrypted
+   *  (for local/internal use only, never public). */
   readonly port?: number;
-  /** TLS-Mode: true = implicit TLS auf port 465, false = STARTTLS auf
-   *  587 (oder plain auf 25). Default false (STARTTLS standard). */
+  /** TLS mode: true = implicit TLS on port 465, false = STARTTLS on
+   *  587 (or plain on 25). The default is false (STARTTLS). */
   readonly secure?: boolean;
-  /** Optional auth — manche internal-relays nehmen IP-whitelisting statt
-   *  Login. Wenn gesetzt, beide felder pflicht. */
+  /** Optional authentication — some internal relays use IP allowlisting
+   *  instead of login. When set, both fields are required. */
   readonly auth?: {
     readonly user: string;
     readonly pass: string;
@@ -120,8 +122,8 @@ export function createSmtpTransport(options: SmtpTransportOptions): EmailTranspo
   };
 }
 
-/** Env-Felder die `createSmtpTransportFromEnv` liest. Apps die SMTP
- *  nutzen extenden ihr env-Schema um genau diese Keys. */
+/** Environment fields read by `createSmtpTransportFromEnv`. Apps that use
+ *  SMTP should extend their environment schema with exactly these keys. */
 export type SmtpEnv = {
   readonly SMTP_HOST?: string;
   readonly SMTP_PORT?: string;
@@ -132,14 +134,15 @@ export type SmtpEnv = {
 };
 
 /**
- * Boot-Time-Transport aus env. Ohne `SMTP_HOST` → `null` (Caller behandelt
- * das als "kein Mail-Versand", statt zu crashen). Port wird zu Number
- * gecoerced (default 587), `secure` ist `SMTP_SECURE === "true"`, auth nur
- * wenn user UND pass gesetzt sind.
+ * Creates a transport at boot time from the environment. Without
+ * `SMTP_HOST`, returns `null` so the caller can treat this as no mail
+ * delivery instead of crashing. The port is coerced to a number (default
+ * 587); `secure` is `SMTP_SECURE === "true"`; authentication is included
+ * only when both the user and password are set.
  *
- * Ersetzt den identischen `env.SMTP_HOST ? createSmtpTransport({...}) : null`
- * Block den jede App in bin/main.ts + bin/server.ts hand-rollte — nur die
- * From-Default (`fallbackFrom`) variiert pro App.
+ * Replaces the repeated `env.SMTP_HOST ? createSmtpTransport({...}) : null`
+ * block that each app previously implemented in bin/main.ts and
+ * bin/server.ts. Only the From default (`fallbackFrom`) varies by app.
  */
 export function createSmtpTransportFromEnv(
   env: SmtpEnv,

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -16,10 +16,9 @@ export const unreadCountQuery = defineQueryHandler({
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
-    // The query helpers in db/query.ts have no aggregate helper — selectMany alle matching rows,
-    // count() in JS. Pragma: unread-counts sind low-cardinality (user-
-    // scoped, max ~hunderte rows). Wenn das wachsen sollte: raw .unsafe()
-    // mit COUNT(*).
+    // The query helpers in db/query.ts have no aggregate helper, so selectMany returns all matching
+    // rows and count() runs in JS. This is acceptable because unread counts are low-cardinality and
+    // user-scoped, with at most a few hundred rows; use raw .unsafe() with COUNT(*) if that grows.
     const rows = await selectMany(ctx.db, inAppMessagesTable, {
       userId: query.user.id,
       isRead: false,

package/packages/bundled-features/src/compliance-profiles/feature.ts

@@ -22,24 +22,23 @@ export {
   tenantComplianceProfileTable,
 } from "./schema/profile-selection.ts";
 
-// compliance-profiles — Tenant-weite DSGVO/Compliance-Profile-Wahl.
+// compliance-profiles — Tenant-wide GDPR/compliance profile selection.
 //
-// Pflicht beim Tenant-Onboarding (Sprint 1.5 Banner-API). Profile
-// buendelt User-Rights-Grace, Notification-Sprache, Breach-Disclosure,
-// Audit-Retention und Sub-Processor-Anforderungen.
+// Required during tenant onboarding. Each profile bundles user-rights grace
+// periods, notification language, breach-disclosure rules, audit retention,
+// and sub-processor requirements.
 //
-// Cross-Feature-API: r.exposesApi("compliance.forTenant") — andere
-// Features (user-data-rights in Sprint 2, tenant-lifecycle in Sprint 5)
-// rufen den Profile-Resolver via QN-Pattern (siehe legal-pages →
-// text-content fuer Pattern-Beispiel).
+// Cross-feature API: r.exposesApi("compliance.forTenant") — other features
+// resolve the profile through the QN pattern (see legal-pages → text-content
+// for an example).
 //
-// Architektur-Note: Profile-Selection lebt als separate Entity
-// (tenantComplianceProfile), nicht als config-key im tenant-Feature.
-// Begruendung in schema/profile-selection.ts.
+// Architectural note: Profile selection is stored as a separate entity
+// (tenantComplianceProfile), not as a config key in the tenant feature.
+// The reason is documented in schema/profile-selection.ts.
 export type ComplianceProfilesFeatureOptions = {
   // Access gate for the profile-picker screen and the `set-profile` write it
   // submits to — both move together so the nav entry a role sees always
-  // matches a callable handler (#2033). Default access.admin includes
+  // matches a callable handler. Default access.admin includes
   // TenantAdmin, who in a line-of-business app is the operator, not the
   // platform — pass access.systemAdmin to keep this platform-only and out
   // of their nav.
@@ -59,10 +58,10 @@ export function createComplianceProfilesFeature(
       category: "compliance",
       recommended: false,
     });
-    // Standalone — kein r.requires noetig: tenantId kommt aus dem User-
-    // Context, Profile-Selection ist eigene Entity, sub-processor-Liste
-    // sind Constants. Wenn S1.4+ Cross-Feature-Reads dazukommen, kommt
-    // r.requires hier rein.
+    // Standalone — r.requires is not needed: tenantId comes from the user
+    // context, profile selection is a separate entity, and the sub-processor
+    // list consists of constants. Add r.requires if cross-feature reads are
+    // introduced.
     r.entity({ name: "tenant-compliance-profile", ...tenantComplianceProfileEntity });
 
     r.exposesApi("compliance.forTenant");

package/packages/bundled-features/src/compliance-profiles/handlers/for-tenant.query.ts

@@ -9,13 +9,10 @@ import * as z from "zod";
 import { parseComplianceProfileOverride } from "../_internal/parse-override.ts";
 import { tenantComplianceProfileTable } from "../schema/profile-selection.ts";
 
-// Liefert das effektive Compliance-Profile fuer den aktuellen Tenant.
-// Macht den exposesApi-Marker aus feature.ts mit echtem Inhalt.
+// Returns the effective compliance profile for the current tenant.
 //
-// Default-Verhalten (Edge-Case-Decision aus S1.1): kein Profile-
-// Eintrag → minimal-no-region + warning="no-profile-selected".
-// Caller (z.B. user-data-rights in Sprint 2) sieht das warning und
-// kann Onboarding-Banner triggern.
+// If no profile is selected, returns minimal-no-region with
+// warning="no-profile-selected" so callers can trigger an onboarding banner.
 export const forTenantQuery = defineQueryHandler({
   name: "for-tenant",
   schema: z.object({}),

package/packages/bundled-features/src/compliance-profiles/handlers/list-profiles.query.ts

@@ -7,12 +7,12 @@ import {
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 
-// Liefert alle waehlbaren Compliance-Profile fuer das Tenant-Onboarding.
-// Pure In-Memory-Read der Constants — keine DB-Abfrage. Kein Caching
-// noetig (modulo Pre-Boot bereits aufgeloest).
+// Returns all selectable compliance profiles for tenant onboarding.
+// Pure in-memory read of the constants—no database query or caching is needed
+// because they are already resolved before boot.
 //
-// Filtert minimal-no-region raus — das ist Default-Fallback, nicht
-// auswählbar (Production soll explizite Wahl treffen).
+// Excludes minimal-no-region because it is the default fallback, not selectable;
+// production must make an explicit choice.
 export const listProfilesQuery = defineQueryHandler({
   name: "list-profiles",
   schema: z.object({}),

package/packages/bundled-features/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -7,7 +7,7 @@ import { tenantComplianceProfileTable } from "../schema/profile-selection.ts";
 
 // Onboarding banner trigger for tenant admin.
 //
-// Sprint 1.5 — minimal API endpoint, the UI banner comes in a later UI
+// Minimal API endpoint, the UI banner comes in a later UI
 // sprint. Pure read query: does an entry exist in tenantComplianceProfile
 // for the current tenant?
 //
@@ -20,7 +20,7 @@ import { tenantComplianceProfileTable } from "../schema/profile-selection.ts";
 // option of createComplianceProfilesFeature) — passing the option through
 // would widen call access by default to all three access.admin roles
 // (including SystemAdmin). Instead the handler takes `pickerReachableRoles`
-// and deliberately resolves the #2063 special case: if the *caller's*
+// and deliberately resolves the special case: if the *caller's*
 // roles no longer intersect the picker's `access` option, the query stops
 // reporting needsSelection — otherwise a tenant admin would be told to
 // open a screen they can't reach.
@@ -37,8 +37,8 @@ export function createNeedsProfileQuery(pickerReachableRoles: readonly string[])
       })) as { profileKey: ComplianceProfileKey } | null; // @cast-boundary db-runner
 
       if (row) {
-        // S1.7 X1: minimal-no-region is no longer settable via set-profile
-        // (Zod). If Sprint 2 ships a seedComplianceProfile helper that
+        // Minimal-no-region is no longer settable via set-profile
+        // (Zod). If a seedComplianceProfile helper ships that
         // reintroduces the migration edge case, a defensive path belongs
         // here again — until then, every existing entry is a deliberately
         // chosen production profile.

package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts

@@ -20,10 +20,10 @@ const crud = createEventStoreExecutor(tenantComplianceProfileTable, tenantCompli
   entityName: "tenant-compliance-profile",
 });
 
-// Schema engt sich auf die 3 oeffentlich waehlbaren Profile (Sprint 1.7
-// X1) — minimal-no-region ist Default-Fallback fuer "noch keine Wahl",
-// nicht eine waehlbare Production-Option. Symmetrisch zu
-// SELECTABLE_PROFILE_KEYS aus der framework/compliance-Liste.
+// The schema is limited to the three publicly selectable profiles.
+// `minimal-no-region` is the default fallback while no choice has been
+// made yet, not a selectable production option. This mirrors
+// SELECTABLE_PROFILE_KEYS from the framework/compliance list.
 const profileKeySchema = z.enum(SELECTABLE_PROFILE_KEYS);
 
 // Upsert: the first call inserts, later calls update, so repeating the same values
@@ -43,8 +43,8 @@ export const setProfileWrite = defineWriteHandler({
     override: z.string().nullable().optional(),
     tenantIdOverride: z.string().min(1).optional(),
   }),
-  // SystemAdmin kann Profile fuer Customer-Setup setzen (Plattform-
-  // Operator-Pfad). TenantAdmin nur fuer eigenen Tenant.
+  // SystemAdmin can set profiles for customer setup through the platform-
+  // operator path; TenantAdmin can set them only for their own tenant.
   access: { roles: access.admin },
   description:
     "Sets or replaces a tenant's compliance profile key plus an optional JSON override, for onboarding or a later region change; a system admin may target a different tenant through tenantIdOverride.",
@@ -52,15 +52,14 @@ export const setProfileWrite = defineWriteHandler({
     const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId) as TenantId; // @cast-boundary engine-payload
     const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 
-    // Override-Validation: muss parseables JSON-Object sein UND dem
-    // ComplianceProfileOverride-Schema entsprechen (S1.9 Z3 — strict-Zod
-    // mit Top-Level + Sub-Level-Whitelist via .strict()). Tippfehler
-    // wie `{ userRights: { weeks: 3 } }` werden hier rejected statt vom
-    // deepMerge silent ins Profile gespliced.
+    // The override must be parseable JSON representing an object and must
+    // conform to the ComplianceProfileOverride schema. The strict Zod
+    // top-level and nested allowlists reject typos such as
+    // `{ userRights: { weeks: 3 } }` instead of silently letting
+    // deepMerge splice them into the profile.
     //
-    // Errors via writeFailure + Kumiko-Error-Klassen (S1.10 M3) statt
-    // throw — landen so mit Path-Detail im response-body statt als
-    // generic internal_error.
+    // writeFailure and Kumiko error classes preserve path details in the
+    // response body instead of producing a generic internal_error.
     if (event.payload.override) {
       let parsed: unknown;
       try {

package/packages/bundled-features/src/compliance-profiles/handlers/sub-processors.query.ts

@@ -8,19 +8,17 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 
-// Public Sub-Processor-Liste — anonymous accessible (Memory:
-// project_anonymous_access). Matched die DSGVO Art. 28(2) Pflicht
-// dass die Liste der Auftragsverarbeiter oeffentlich einsehbar ist
-// (typisch verlinkt aus Datenschutzerklaerung + AVV).
+// Public sub-processor list, accessible anonymously. This satisfies the GDPR Art. 28(2) requirement
+// that the list of processors be publicly accessible, typically linked from
+// the privacy policy and data-processing agreement.
 //
-// Format: JSON mit getrennten active/planned-Sektionen. Tenant-Admins
-// kriegen Notification ueber Aenderungen via Cron-Job (Sprint 1.5+
-// oder S9 compliance-as-product). RSS-Feed kommt in S9.
+// Format: JSON with separate active/planned sections. Tenant admins receive
+// change notifications via a cron job.
 //
-// Zwei Auflistungen statt einer flachen Liste:
-//   - `active`: aktuell eingesetzte Sub-Processors
-//   - `planned`: bekannte zukünftige Sub-Processors (Tenant-Admin-
-//     Lead-Time bevor sie aktiv werden — typisch bei AI/Stripe)
+// Two lists are used instead of one flat list:
+//   - `active`: sub-processors currently in use
+//   - `planned`: known future sub-processors, giving tenant admins lead time
+//     before activation, as is typical for AI and Stripe providers.
 export const subProcessorsQuery = defineQueryHandler({
   name: "sub-processors",
   schema: z.object({}),

package/packages/bundled-features/src/compliance-profiles/resolve-for-tenant.ts

@@ -1,12 +1,12 @@
-// Direkter Resolver-Helper fuer Bulk-Iteration ohne dispatcher-Roundtrip.
+// Direct resolver helper for bulk iteration without a dispatcher round trip.
 //
-// `for-tenant`-Query (handlers/for-tenant.query.ts) ist die Cross-Feature-
-// API fuer Handler-Pfade. Worker (S2.U3 Atom 3b) lebt im JobContext
-// ohne `queryAs` — braucht direkten DB-Lookup + resolveComplianceProfile.
+// The `for-tenant` query (handlers/for-tenant.query.ts) is the cross-feature
+// API for handler paths. Workers run in JobContext (without `queryAs`), so
+// they need a direct database lookup followed by `resolveComplianceProfile`.
 //
-// Pattern matched data-retention's `resolveRetentionPolicyForTenant`.
-// Beide Pfade nutzen `resolveComplianceProfile` aus framework/compliance,
-// also kein Drift zwischen Query-API und Worker-Pfad.
+// This follows data-retention's `resolveRetentionPolicyForTenant` pattern.
+// Both paths use `resolveComplianceProfile` from framework/compliance, keeping
+// the query API and worker path consistent.
 
 import {
   type ComplianceProfileKey,

package/packages/bundled-features/src/compliance-profiles/schema/profile-selection.ts

@@ -5,24 +5,19 @@ import {
   createSelectField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Tenant-1-zu-1: Pro Tenant genau eine Profile-Wahl.
+// One-to-one relationship: each tenant has exactly one profile selection.
 //
-// Architektur-Entscheidung (2026-05-06): Profile-Selection lebt als
-// separate Entity im compliance-profiles-Feature, NICHT als config-key
-// im tenant-Feature. Begruendung:
-//   (a) override ist strukturiertes JSON, config-key-Pattern (timezone/
-//       locale) ist key-value-flach
-//   (b) Profile-Wechsel ist audit-relevant — Event-Store gibt das
-//       automatisch fuer Entity-Writes
-//   (c) Plan-Files in docs/plans/datenschutz/compliance-profiles.md
-//       nennen sie explizit als tenantComplianceProfile-Entity
+// Profile selection is a separate entity in the compliance-profiles feature,
+// not a config key in the tenant feature, because:
+//   (a) override is structured JSON, while the config-key pattern
+//       (timezone/locale) is flat key-value data
+//   (b) profile changes are audit-relevant, which the event store handles
+//       automatically for entity writes
 //
-// Wer in 6 Monaten zweifelt warum nicht config-key: siehe oben.
-//
-// override als JSON-String in longText: kein dedizierter jsonField-Typ
-// im Framework; embedded hat festes Schema, das hier dynamisch ist.
-// Zod-Validation beim set-profile-Handler stellt Schema-Konformitaet
-// sicher.
+// override is stored as a JSON string in longText because the framework has
+// no dedicated jsonField type; embedded has a fixed schema, while this schema
+// is dynamic. Zod validation in the set-profile handler ensures schema
+// conformity.
 export const tenantComplianceProfileEntity = createEntity({
   table: "read_tenant_compliance_profiles",
   fields: {
@@ -30,19 +25,19 @@ export const tenantComplianceProfileEntity = createEntity({
       required: true,
       options: ["eu-dsgvo", "swiss-dsg", "de-hr-dsgvo-hgb", "minimal-no-region"] as const,
     }),
-    // override: JSON-String mit Partial-ComplianceProfile. NULL/leer
-    // bedeutet "Default-Profile, keine Override". Validiert beim
-    // set-profile-Handler via Zod.
+    // override: JSON string containing a partial ComplianceProfile. NULL/empty
+    // means "default profile, no override". Validated by the
+    // set-profile handler via Zod.
     override: createLongTextField({
       personal: false,
       reason: "is_business_data",
     }),
   },
   indexes: [
-    // Pro Tenant nur EIN Profile-Datensatz. Boot-Validator-Comment in
-    // EntityIndexDef warnt vor single-column-tenantId-Index als redundant
-    // — UNIQUE-Constraint ist hier aber semantisch noetig (1:1-Relation)
-    // und nicht nur Performance-Hint, daher explizit deklariert.
+    // Only one profile record is allowed per tenant. Although the boot validator
+    // warns that a single-column tenantId index is redundant, the UNIQUE
+    // constraint is semantically required here for the one-to-one relationship,
+    // not merely a performance hint, so it is declared explicitly.
     { unique: true, columns: ["tenantId"] },
   ],
 });

package/packages/bundled-features/src/compliance-profiles/seeding.ts

@@ -1,14 +1,14 @@
-// Test-Helper für compliance-profiles. Legt einen Profile-Eintrag direkt
-// über den Event-Store-Executor an — gleicher Pfad wie der echte
-// set-profile-Handler, aber ohne Zod-Schema-Engung (akzeptiert
-// minimal-no-region für Migration-Edge-Case-Tests) und ohne Access-
-// Check. Default ifExists="skip": nur fehlende Profile anlegen.
+// Test helper for compliance-profiles. Creates a profile entry directly
+// through the Event Store executor—the same path as the real
+// set-profile handler, but without Zod schema restrictions (accepts
+// minimal-no-region for migration edge-case tests) and without an access
+// check. Default ifExists="skip": creates only missing profiles.
 //
-// Sprint 2 user-data-rights nutzt das fuer Test-Setup ("user kann
-// Daten exportieren mit profile X" — pro Test ein frischer Tenant +
-// Profile-Wahl in einem Helper-Call).
+// user-data-rights uses this for test setup ("user can export data with
+// profile X": a fresh tenant and profile selection per test in one helper
+// call).
 //
-// Pattern matched seedTextBlock aus text-content.
+// The pattern matches seedTextBlock in template-resolver/seeding.ts.
 
 import type {
   ComplianceProfileKey,
@@ -50,9 +50,8 @@ export async function seedComplianceProfile(
   db: DbConnection,
   opts: SeedComplianceProfileOptions,
 ): Promise<{ id: string }> {
-  // user.tenantId muss === opts.tenantId sein damit Event-Store-Stream
-  // + Projection im selben Tenant-Bucket landen (Memory:
-  // feedback_event_store_tenant_consistency).
+  // user.tenantId must equal opts.tenantId so the Event Store stream
+  // and projection remain in the same tenant bucket.
   const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
   const tdb = createTenantDb({ db, tenantId: opts.tenantId, mode: "system" });
   const overrideJson = opts.override !== undefined ? JSON.stringify(opts.override) : null;
@@ -77,9 +76,9 @@ export async function seedComplianceProfile(
       if (!result.isSuccess) {
         throw new Error(`seedComplianceProfile create failed: ${JSON.stringify(result)}`);
       }
-      // @cast-boundary db-row: executor.create result.data ist die
-      // inserted Projection-Row (Record<string, unknown>); id ist nach
-      // INSERT garantiert (Runtime-Check direkt darunter).
+      // @cast-boundary db-row: executor.create result.data is the
+      // inserted projection row (Record<string, unknown>); id is guaranteed
+      // after INSERT (runtime check directly below).
       const data = result.data as { id?: string };
       if (data.id === undefined) {
         throw new Error("seedComplianceProfile: executor.create did not return an id");

package/packages/bundled-features/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -5,12 +5,12 @@ import * as z from "zod";
 import { tenantComplianceProfileTable } from "../../compliance-profiles/index.ts";
 import { decryptTenantNames, tenantTable } from "../../tenant/index.ts";
 
-// SystemAdmin platform-wide counterpart to needs-profile (#2089).
+// SystemAdmin platform-wide counterpart to needs-profile.
 //
-// #2084 stopped needs-profile from nagging a TenantAdmin who can no longer
+// The change stopped needs-profile from nagging a TenantAdmin who can no longer
 // reach a picker narrowed to access.systemAdmin — correct, but it left no
 // one else able to notice: needs-profile stays TenantAdmin-only on purpose
-// (widening its call-access was explicitly rejected in #2084), so a
+// (widening its call-access was explicitly rejected), so a
 // SystemAdmin who owns the platform-only picker has no way to see which
 // tenants still run on minimal-no-region. This query fills that gap
 // instead of touching needs-profile: every enabled tenant that has no row

package/packages/bundled-features/src/compliance-profiles-ops/index.ts

@@ -1,8 +1,8 @@
 // compliance-profiles-ops — platform-wide SystemAdmin visibility into
-// tenants missing a compliance-profile selection (#2089).
+// tenants missing a compliance-profile selection.
 //
 // needs-profile (compliance-profiles) tells a TenantAdmin they must pick a
-// profile, but stays TenantAdmin-only by design (#2084) — a SystemAdmin who
+// profile, but stays TenantAdmin-only by design — a SystemAdmin who
 // owns a picker narrowed to access.systemAdmin has no query at all. Kept as
 // a separate feature (mirrors folders-user-data/notes-history-user-data)
 // rather than folded into compliance-profiles: this is the one genuinely

package/packages/bundled-features/src/config/handlers/readiness.query.ts

@@ -74,17 +74,17 @@ export async function collectMissingRequiredConfig(
   db: TenantDb,
   gate?: RequiredKeyGate,
   options?: {
-    /** Verdict-Pfade (Rollup, selbst role-gated) MÜSSEN ungefiltert zählen:
-     *  der Per-Key-read-Filter ist Info-Disclosure-Schutz für den
-     *  openToAll-Handler — im Verdict droppte er SystemAdmin-gated
-     *  required-Keys still und meldete ready:true trotz Lücke. */
+    /** Verdict paths (rollup, themselves role-gated) MUST count without filtering:
+     *  the per-key read filter protects the openToAll handler from information
+     *  disclosure, but in the verdict it dropped SystemAdmin-gated required keys
+     *  and incorrectly reported ready:true despite the gap. */
     readonly skipAccessFilter?: boolean;
   },
 ): Promise<ReadinessMissingKey[]> {
   const resolver = requireConfigResolver(ctx, callerQn);
   const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user, db));
-  // Kandidaten erst sammeln, dann EIN Batch-Resolve — die sequentielle
-  // resolver.get-Schleife war ein N+1 über alle required Keys (272/1).
+  // Collect candidates first, then perform ONE batch resolve — the sequential
+  // resolver.get loop was an N+1 operation across all required keys (272/1).
   type KeyDef =
     ReturnType<typeof ctx.registry.getAllConfigKeys> extends ReadonlyMap<string, infer D>
       ? D
@@ -153,7 +153,7 @@ export const readinessQuery = defineQueryHandler({
       db,
     );
     // Additive, display-ready fields for the admin-shell dashboard stat
-    // panel (fw#2312) — `missing` itself stays untouched for existing
+    // panel — `missing` itself stays untouched for existing
     // consumers that read the array directly.
     return {
       missing,

package/packages/bundled-features/src/config/handlers/reencrypt.job.ts

@@ -16,8 +16,8 @@
 // the NEW envelope: after a full run even a from-scratch rebuild only
 // ever sees the current-KEK envelope.
 //
-// systemScope() fail-closed pattern (framework#2056): the initial scan is
-// intentionally cross-tenant (system-wide key rotation), acknowledged via
+// systemScope() fail-closed pattern: the initial scan is intentionally
+// cross-tenant (system-wide key rotation), acknowledged via
 // UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
 // and assertRowsTenant() re-verifies each row against its bucket's tenant
 // right before the write — both checks are built locally from the exported
@@ -226,9 +226,8 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     }
 
     // Re-verify the row's own tenantId against the bucket it was scanned
-    // into, right before the write (framework#2072) — a mismatch here
-    // fails this row only (via onRowError below), it does not abort the
-    // whole job.
+    // into, right before the write — a mismatch here fails this row only
+    // (via onRowError below), it does not abort the whole job.
     sdbFor(tenantId).assertRowsTenant([row], "tenantId");
 
     const plaintext = await cipher.decrypt(row.value, { tenantId });

package/packages/bundled-features/src/config/handlers/set.write.ts

@@ -74,7 +74,8 @@ export const setWrite = defineWriteHandler({
     // rejected), but an admin override write can still target scope=
     // "system" for a tenant/user-scoped key (validateScope allows any
     // requestedScope <= definedScope) — system-row has no subject.
-    if (keyDef.piiEncrypted && scope === ConfigScopes.system) {
+    const piiScope = keyDef.piiEncrypted && scope !== ConfigScopes.system ? scope : undefined;
+    if (keyDef.piiEncrypted && piiScope === undefined) {
       return writeFailure(
         new UnprocessableError("invalid_scope", {
           i18nKey: "config.errors.invalidScope",
@@ -153,7 +154,7 @@ export const setWrite = defineWriteHandler({
     if (keyDef.encrypted) {
       const cipher = requireConfigEncryption(ctx, "config:write:set");
       serialized = await cipher.encrypt(serialized, { tenantId });
-    } else if (keyDef.piiEncrypted) {
+    } else if (piiScope !== undefined) {
       const kms = configuredPiiSubjectKms();
       if (!kms) {
         throw new InternalError({
@@ -163,8 +164,7 @@ export const setWrite = defineWriteHandler({
             `configurePiiSubjectKms(adapter) at boot.`,
         });
       }
-      // scope="system" was already rejected above — narrow accordingly.
-      const subject = resolvePiiSubject(scope as Exclude<typeof scope, "system">, tenantId, userId);
+      const subject = resolvePiiSubject(piiScope, tenantId, userId);
       const kmsCtx: KmsContext = {
         requestId: requestContext.get()?.requestId ?? "config:write:set",
         tenantId,

package/packages/bundled-features/src/config/resolver.ts

@@ -583,10 +583,10 @@ export function validateAppOverrides(
       );
     }
 
-    // Per keyDef.type narrow value inline — TS narrowt nicht durch
-    // `typeof value !== typeForKey(...)` (typeForKey returnt string,
-    // kein discriminator). Das vermeidet `value as string|number` casts
-    // unten, weil value innerhalb des Branches schon typed ist.
+    // Narrow by keyDef.type inline because TypeScript cannot narrow through
+    // `typeof value !== typeForKey(...)`, whose return type is string rather
+    // than a discriminator. This avoids `value as string|number` casts below;
+    // value is correctly typed within each branch.
     if (keyDef.type === "number") {
       if (typeof value !== "number") {
         throw new Error(`App-Boot-Override for "${key}": expected number, got ${typeof value}`);