@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

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

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

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

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

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

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

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

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

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

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

@@ -1,8 +1,7 @@
-// /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.ts";

package/packages/bundled-features/src/tenant/web/constants.ts

@@ -21,11 +21,11 @@ export const MEMBER_ROLES_CELL_COMPONENT = "MemberRolesCell" as const;
 
 /** Closed allowlist for invite-role picker — never free text (escalation guard). */
 // Admin (rank 2) shares the invite-create screen with TenantAdmin — TenantAdmin
-// must not appear here or Admin sees an unassignable option (fw#2414).
+// must not appear here or Admin sees an unassignable option.
 export const DEFAULT_INVITE_ROLE_OPTIONS = ["User", "Editor", "Admin"] as const;
 // Full rank list for memberRolesEditScreen: it is prefilled with a member's
 // *current* roles, so it must represent every rank a membership can hold,
-// including TenantAdmin (fw#2452). The screen hides what the caller may not
+// including TenantAdmin. The screen hides what the caller may not
 // assign via TenantQueries.memberRoleAvailability.
 export const OWNER_INVITE_ROLE_OPTIONS = [
   "User",

package/packages/bundled-features/src/tenant-handover/events.ts

@@ -1,12 +1,10 @@
 import * as z from "zod";
 
-// Audit trail for a completed claim (kumiko-framework#3035's audit-entry
-// requirement: names the source tenant, destination tenant, entities and
-// their counts). Its own aggregate, decoupled from the transferred root's
-// stream — same reasoning as
-// sessions' SESSION_REVOKED_EVENT: a fresh aggregate id per occurrence needs
-// no predecessor version and can never conflict with a concurrent write on
-// the entity it describes.
+// Audit trail for a completed claim (audit-entry requirement: names the source tenant, destination
+// tenant, entities and their counts). Its own aggregate, decoupled from the transferred root's
+// stream — same reasoning as sessions' SESSION_REVOKED_EVENT: a fresh aggregate id per occurrence
+// needs no predecessor version and can never conflict with a concurrent write on the entity it
+// describes.
 //
 // _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes it
 //          to the QN below.

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

@@ -9,7 +9,7 @@ import { createSignupHandoverProvider } from "./signup-handover-provider.ts";
 
 export type TenantHandoverFeatureOptions = ClaimTenantHandoverOptions;
 
-// tenant-handover — Option A from kumiko-framework#3035: the ONE write a
+// tenant-handover — the ONE write a
 // try-before-signup (or guest-checkout, demo-to-account) flow needs once an
 // anonymous run is done and the visitor has a fresh tenant. No general
 // tenant-merge tool, no copy — this is an ownership change on rows a

package/packages/bundled-features/src/tenant-handover/grant.ts

@@ -1,4 +1,4 @@
-// Try-before-signup ownership handover (kumiko-framework#3035), expressed as a
+// Try-before-signup ownership handover, expressed as a
 // row-bound grant: the subject is the transferred run's own row id, the
 // anchor is the SOURCE tenant id it currently lives under. Redeeming the
 // grant is the ownership change itself — the claim handler's commitAnchor

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

@@ -31,7 +31,7 @@ function notTransferable(entityType: string): ReturnType<typeof writeFailure> {
   );
 }
 
-// The try-before-signup ownership handover (kumiko-framework#3035): claims an
+// The try-before-signup ownership handover: claims an
 // anonymous run into the caller's own tenant, legitimized by a row-bound
 // grant the anonymous flow minted (see ../grant.ts). Idempotent — a second
 // call with the same token fails the same way a forged one would, because

package/packages/bundled-features/src/tenant-handover/move-entity-graph.ts

@@ -1,4 +1,4 @@
-// The actual ownership change (kumiko-framework#3035): raw SQL against the
+// The actual ownership change: raw SQL against the
 // read-model tables, because moving a row across the tenant boundary is
 // exactly the kind of write the framework's entity write map cannot express
 // (it is single-tenant-scoped by design — that boundary is the whole point
@@ -15,10 +15,10 @@
 // `transaction()` call, rolling back everything the handler already did).
 // `moveRootRow` — called as row-bound-grant's `commitAnchor` — is therefore
 // the ONLY statement that must itself combine the anchor-spend with the
-// first write (#3023's hard rule: a write issued after `ok: true` can lose
-// its work to a crash while the grant is already burned). Everything after
+// first write: a write issued after `ok: true` can lose
+// its work to a crash while the grant is already burned. Everything after
 // it rides the same transaction: if a later step throws (an undeclared
-// child entity, kumiko-framework#3035's named-error requirement), the WHOLE
+// child entity, the named-error requirement), the WHOLE
 // transaction — root row included — rolls back, so a caller can safely
 // retry the same token after fixing the app's `transferable` declarations.
 
@@ -64,8 +64,7 @@ export async function moveRootRow(args: {
 // history + storage-usage counters — fileRef is a standard ES entity (see
 // files-storage-tracking.md), so without those two follow-ups a later write
 // against a moved fileRef can't load its stream, and a projection rebuild
-// would put the row back into the source tenant (kumiko-framework#3131-adjacent
-// gap, item 4).
+// would put the row back into the source tenant.
 async function moveFileRefs(args: {
   readonly db: DbRunner;
   readonly registry: Registry;
@@ -210,7 +209,7 @@ async function moveEdgeRows(args: {
 // Everything the root ownership write does NOT cover: the root's own event
 // history + attached files, plus the rows, event history and attached files of
 // every descendant the declared transfer graph reaches, however deep and by
-// however many paths (#3088, #3131).
+// however many paths.
 // Returns a count per moved entity name (the
 // write handler turns this into the audit entry) — `fileRef` is a single
 // pooled count across root + every child, since it is not itself part of the
@@ -264,7 +263,7 @@ export async function moveTransferGraph(args: {
 
   const adjacency = resolveTransferAdjacency(registry, rootEntityName);
 
-  // A worklist, not a level-wise walk (#3131): each batch of rows that actually
+  // A worklist, not a level-wise walk: each batch of rows that actually
   // changed hands becomes the parent ids for the edges leading away from its
   // type. The same edge therefore runs again whenever a later round discovers
   // more rows of its parent type, which is what a type reachable by two paths
@@ -274,7 +273,7 @@ export async function moveTransferGraph(args: {
   // every statement filters on `tenantCol = sourceTenantId` and RETURNS only
   // the rows it flipped, so a row enters this worklist exactly once and the
   // source tenant holds finitely many. Do not add an edge-level visited set to
-  // "bound" this — that is precisely the bug #3131 removed.
+  // "bound" this — that would reintroduce the bug.
   let pending: readonly { readonly entityName: string; readonly rowIds: readonly string[] }[] = [
     { entityName: rootEntityName, rowIds: [rootRowId] },
   ];

package/packages/bundled-features/src/tenant-handover/signup-handover-provider.ts

@@ -1,6 +1,5 @@
 // tenant-handover's implementation of the shared signup-handover extension
-// point (kumiko-framework#3035 follow-up, offlot-app#454): lets
-// auth-email-password's signup-request verify a grant against its root row
+// point: lets auth-email-password's signup-request verify a grant against its root row
 // WITHOUT spending the anchor (the anchor is spent once, by the claim
 // signup-confirm runs afterwards, via a fresh short-lived grant this module
 // mints) — see shared/signup-handover.ts for the extension contract and

package/packages/bundled-features/src/tenant-handover/transfer-graph.ts

@@ -1,15 +1,14 @@
 // Resolves the declared transfer graph for a root entity type: the root
 // itself, plus every registered entity that reaches it through a declared
-// schema edge (kumiko-framework#3035, #3088; framework CLAUDE.md premise 4 —
-// the graph depth is read off the existing declarations, never a hand-
-// maintained per-app list).
+// schema edge (framework CLAUDE.md premise 4 — the graph depth is read off
+// the existing declarations, never a hand-maintained per-app list).
 //
 // The edge definition (parentRef + single-valued reference fields, minus
 // `handover: "stay"`) lives in the framework so the boot validator's depth
 // limit and the mover's traversal measure the same graph. What comes out is
 // static adjacency, not a walk: the mover drives the actual traversal from the
-// row ids it moves (#3131), because how deep a type sits depends on the rows
-// found, not on the schema alone.
+// row ids it moves, because how deep a type sits depends on the rows found,
+// not on the schema alone.
 //
 // `transferable: true` stays the only gate on what actually moves, and it is
 // enforced by the caller against edges that turn out to have rows rather than

package/packages/bundled-features/src/tenant-lifecycle/boot-checks.ts

@@ -16,7 +16,7 @@ const log = createFallbackLogger("kumiko:boot");
 
 // V4: tenantOwned-entity-without-hook gate. Mirrors user-data-rights' V3
 // (validateGdprPiiHookCoverage) but for EXT_TENANT_DATA. Registered as this
-// feature's own `r.bootCheck()` (#1314, moved off the framework-internal
+// feature's own `r.bootCheck()` (moved off the framework-internal
 // boot-validator) — tenant-lifecycle owns EXT_TENANT_DATA
 // (r.extendsRegistrar), so its own mount is the trigger, matching the
 // original guard's "tenant-lifecycle mounted" gate exactly (unlike gating on

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

@@ -78,7 +78,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
     r.extendsRegistrar(EXT_TENANT_LIFECYCLE_STATUS, {});
     r.useExtension(EXT_TENANT_LIFECYCLE_STATUS, "tenant-lifecycle", tenantLifecycleStatusPlugin);
 
-    // GDPR-storage guard V4 (#1314) — moved off the framework-internal
+    // GDPR-storage guard V4 — moved off the framework-internal
     // boot-validator onto this feature's own r.bootCheck(), since it owns
     // EXT_TENANT_DATA: its own mount is the trigger, matching the original
     // guard's "tenant-lifecycle mounted" gate exactly.

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -427,7 +427,7 @@ export async function runTenantDestructionSweep(args: {
 
   let triggered = 0;
   for (const row of due) {
-    const tenantId = row.id as TenantId;
+    const tenantId = row.id;
     const events = await loadAggregate(args.db, tenantId, tenantId);
     const version = lastEventVersion(events);
     const user = createSystemUser(tenantId);
@@ -469,7 +469,7 @@ export async function runTenantDestructionSweep(args: {
         deadlineAt: tenantDeadlineAt,
         db: args.db,
         registry: args.registry,
-        tenantId: row.id as TenantId,
+        tenantId: row.id,
         log: args.log,
         fileProviderResolver: args.fileProviderResolver,
         searchAdapter: args.searchAdapter,

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -60,7 +60,7 @@ export type DestructionStageCtx = {
   // Derived search docs of the tenant record (its name) live in the writer's
   // index, not the destroyed tenant's, so the subject-keys stage purges them.
   readonly searchAdapter?: SearchAdapter;
-  // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
+  // Sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); runTenantDataHooks uses them to attribute+audit any
   // EXT_TENANT_DATA usage's declared escapeHatch.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;

package/packages/bundled-features/src/tenant-settings/constants.ts

@@ -14,7 +14,7 @@ export const TENANT_SETTINGS_FEATURE_NAME = "tenant-settings";
 // strings (mirror tags' Handlers/Queries constants).
 export const TenantSettingsConfig = {
   // Shared with engine/constants.ts's TENANT_CURRENCY_CONFIG_KEY — a
-  // `money` field's `currency: { kind: "tenant" }` declaration (fw#2933)
+  // `money` field's `currency: { kind: "tenant" }` declaration
   // resolves against this same key.
   currency: TENANT_CURRENCY_CONFIG_KEY,
   locale: "tenant-settings:config:locale",

package/packages/bundled-features/src/tenant-settings/tenant-defaults.ts

@@ -15,6 +15,8 @@ import {
   type EntityDefinition,
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { TenantSettingsConfig } from "./constants.ts";
 
@@ -26,7 +28,7 @@ export function defineCreateWithTenantDefaults(
   options: {
     /** Required — this is a write-path helper; making it optional let a
      *  forgetful caller register a create handler with no access rule at
-     *  all (fw#1581). */
+     *  all. */
     readonly access: AccessRule;
     /** Money field names whose `currency` is filled from tenant-settings when missing. */
     readonly currencyFields?: readonly string[];
@@ -53,11 +55,16 @@ export function defineCreateWithTenantDefaults(
     schema,
     access: options.access,
     handler: async (event, ctx) => {
-      const payload = { ...(event.payload as Record<string, unknown>) };
+      if (!isPlainObject(event.payload)) {
+        throw new InternalError({
+          message: `${entityName}:create payload must be an object after schema validation`,
+        });
+      }
+      const payload = { ...event.payload };
 
       for (const field of options.currencyFields ?? []) {
-        const value = payload[field] as { amount?: number; currency?: string } | undefined;
-        if (value && typeof value === "object" && !value.currency) {
+        const value = payload[field];
+        if (isPlainObject(value) && !value["currency"]) {
           const currency = await ctx.config?.(TenantSettingsConfig.currency);
           if (typeof currency === "string") payload[field] = { ...value, currency };
         }
@@ -68,7 +75,7 @@ export function defineCreateWithTenantDefaults(
       }
 
       // Re-validate against the unrelaxed entity schema so config-filled
-      // values still honor select/enum field constraints (fw#1581) — and so
+      // values still honor select/enum field constraints — and so
       // a missing currency after failed/missing tenant-settings mount fails
       // loud instead of inserting half-filled money rows.
       const filled = baseSchema.parse(payload);

package/packages/bundled-features/src/tier-engine/aggregate-id.ts

@@ -1,26 +1,25 @@
 import { v5 as uuidv5 } from "uuid";
 
-// Fixed UUID-namespace für die tier-assignment-aggregate-id-Ableitung.
-// Generiert einmalig (2026-05-02), in Stein gemeißelt: ein Wechsel würde
-// jeden existing aggregate-Stream re-keyen → kaputter event-replay,
-// kaputte projection-rebuilds, verlorener Tier-Wechsel-Audit. Der
-// drift-pin-Test in feature.test.ts pinnt diese Konstante.
+// Fixed UUID namespace for deriving tier-assignment aggregate IDs.
+// Generated once and immutable: changing it would re-key every existing
+// aggregate stream, breaking event replay and projection rebuilds and losing
+// the tier-change audit. The drift-pin test in feature.test.ts pins this constant.
 const TIER_ASSIGNMENT_NAMESPACE = "8e91d2fc-8b7a-4d3e-9f4a-1c5d6e7f8a9b";
 
 /**
- * Deterministic aggregate-id für ein Tier-Assignment aus dem tenantId.
- * Pro Plattform-Tenant existiert genau ein Aggregat — uuidv5 ist
- * namespace-deterministic, identische Eingabe ergibt identischen UUID.
+ * Deterministic aggregate ID for a tier assignment derived from `tenantId`.
+ * Each platform tenant has exactly one aggregate; uuidv5 is namespace-
+ * deterministic, so identical input produces the same UUID.
  *
- * **Wann nutzen:** Sprint 5 (`stripe-sync`-Feature) wrapt einen
- * idempotent-set-tier-Handler darum: zweiter Stripe-Webhook-Retry mit
- * derselben tenantId → derselbe aggregate-Stream → version_conflict
- * vom Event-Store statt pg-23505 von der Read-Model-DB. ES-saubere
- * Path-Uniqueness statt DB-Constraint.
+ * **When to use:** The `stripe-sync` feature wraps an idempotent
+ * set-tier handler with this function: a second Stripe webhook retry for
+ * the same `tenantId` targets the same aggregate stream, causing
+ * `version_conflict` from the event store instead of `pg-23505` from the
+ * read-model database. This enforces path uniqueness rather than a database
+ * constraint.
  *
- * **Sprint 1 nutzt das nicht aktiv** — Standard-CRUD-Handlers vergeben
- * UUID via `gen_random_uuid()`. Die Funktion lebt hier als Utility-
- * Export bereit für Sprint 5.
+ * Standard CRUD handlers instead generate UUIDs via `gen_random_uuid()`.
+ * This utility is exported for use by the `stripe-sync` feature.
  */
 // @wrapper-known uuid-domain
 export function tierAssignmentAggregateId(tenantId: string): string {