@cosmicdrift/kumiko-samples 0.368.0 → 0.370.0

package/packages/bundled-features/src/waitlist/handlers/export-purge.write.ts

@@ -0,0 +1,81 @@
+import { defineWriteHandler, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import {
+  WAITLIST_AUDIT_AGGREGATE_TYPE,
+  WAITLIST_EXPORTED_EVENT_QN,
+  WAITLIST_PURGED_EVENT_QN,
+  WaitlistErrors,
+} from "../constants.ts";
+import { listAllWaitlistRows, purgeWaitlistRows } from "../entries-admin.ts";
+import { adminAccess, waitlistDb } from "../lib.ts";
+
+export type WaitlistExportData = {
+  readonly count: number;
+  readonly entries: readonly Record<string, unknown>[];
+};
+export type WaitlistPurgeData = { readonly purged: number };
+
+const PurgeSchema = z.object({ confirmCount: z.number().int().min(0) }).strict();
+const ExportSchema = z.object({}).strict();
+
+async function appendAudit(ctx: HandlerContext, type: string, count: number): Promise<void> {
+  await ctx.unsafeAppendEvent({
+    aggregateId: generateId(),
+    aggregateType: WAITLIST_AUDIT_AGGREGATE_TYPE,
+    type,
+    payload: { count },
+  });
+}
+
+function exportedRow(row: Record<string, unknown>): Record<string, unknown> {
+  return {
+    id: row["id"],
+    name: row["name"],
+    email: row["email"],
+    company: row["company"],
+    portfolio: row["portfolio"],
+    message: row["message"],
+    locale: row["locale"],
+    status: row["status"],
+    submittedAt: String(row["submittedAt"] ?? ""),
+  };
+}
+
+export const exportHandler = defineWriteHandler<"export", typeof ExportSchema, WaitlistExportData>({
+  name: "export",
+  schema: ExportSchema,
+  access: adminAccess,
+  agent: { expose: false, risk: "high" },
+  description:
+    "Returns every waitlist entry with its personal data for a hand-over and records the export as an audit event that carries only the count.",
+  handler: async (_event, ctx) => {
+    const rows = await listAllWaitlistRows(waitlistDb(ctx));
+    await appendAudit(ctx, WAITLIST_EXPORTED_EVENT_QN, rows.length);
+    return { isSuccess: true, data: { count: rows.length, entries: rows.map(exportedRow) } };
+  },
+});
+
+export const purgeHandler = defineWriteHandler<"purge", typeof PurgeSchema, WaitlistPurgeData>({
+  name: "purge",
+  schema: PurgeSchema,
+  access: adminAccess,
+  agent: { expose: false, risk: "high" },
+  description:
+    "Erases every waitlist entry and shreds its personal data. confirmCount must equal the current entry count, so a stale export cannot purge newer entries.",
+  handler: async (event, ctx) => {
+    const db = waitlistDb(ctx);
+    const rows = await listAllWaitlistRows(db);
+    if (rows.length !== event.payload.confirmCount) {
+      return writeFailure(
+        new UnprocessableError(WaitlistErrors.confirmCountMismatch, {
+          details: { confirmCount: event.payload.confirmCount, actualCount: rows.length },
+        }),
+      );
+    }
+    await purgeWaitlistRows(db, rows, event.user.id);
+    await appendAudit(ctx, WAITLIST_PURGED_EVENT_QN, rows.length);
+    return { isSuccess: true, data: { purged: rows.length } };
+  },
+});

package/packages/bundled-features/src/waitlist/handlers/invite.write.ts

@@ -14,19 +14,19 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { AuthErrors, AuthHandlers } from "../../auth-email-password/index.js";
-import { TenantHandlers, tenantTable } from "../../tenant/index.js";
-import { DEFAULT_OWN_TENANT_INVITE_ROLE, WAITLIST_STATUS, WaitlistErrors } from "../constants.js";
-import { isOpenWaitlistStatus } from "../entity.js";
+import { AuthErrors, AuthHandlers } from "../../auth-email-password/index.ts";
+import { TenantHandlers, tenantTable } from "../../tenant/index.ts";
+import { DEFAULT_OWN_TENANT_INVITE_ROLE, WAITLIST_STATUS, WaitlistErrors } from "../constants.ts";
+import { isOpenWaitlistStatus } from "../entity.ts";
 import {
   adminAccess,
   isTenantMember,
   platformActor,
   waitlistDb,
   waitlistExecutor,
-} from "../lib.js";
-import type { WaitlistInviteOptions } from "../options.js";
-import { WaitlistIdSchema } from "../payloads.js";
+} from "../lib.ts";
+import type { WaitlistInviteOptions } from "../options.ts";
+import { WaitlistIdSchema } from "../payloads.ts";
 
 export type WaitlistInviteData = {
   readonly kind: "invited";

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

@@ -1,6 +1,6 @@
 import { defineEntityListHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { waitlistEntryEntity } from "../entity.js";
-import { adminAccess } from "../lib.js";
+import { waitlistEntryEntity } from "../entity.ts";
+import { adminAccess } from "../lib.ts";
 
 // Entity-convention list: the QN waitlist:query:waitlist-entry:list is what the
 // entityList screen resolves; paging, search and sort come from the entity flags.

package/packages/bundled-features/src/waitlist/handlers/reject.write.ts

@@ -16,9 +16,9 @@ import {
   cancelPendingInvitation,
   INVITATION_STATUS,
   tenantInvitationsTable,
-} from "../../tenant/index.js";
-import { WAITLIST_STATUS, WaitlistErrors } from "../constants.js";
-import { isOpenWaitlistStatus } from "../entity.js";
+} from "../../tenant/index.ts";
+import { WAITLIST_STATUS, WaitlistErrors } from "../constants.ts";
+import { isOpenWaitlistStatus } from "../entity.ts";
 import {
   adminAccess,
   isTenantMember,
@@ -26,8 +26,8 @@ import {
   platformActor,
   waitlistDb,
   waitlistExecutor,
-} from "../lib.js";
-import { WaitlistIdSchema } from "../payloads.js";
+} from "../lib.ts";
+import { WaitlistIdSchema } from "../payloads.ts";
 
 export type WaitlistRejectData = { readonly kind: "rejected"; readonly id: string };
 

package/packages/bundled-features/src/waitlist/handlers/submit.write.ts

@@ -7,20 +7,20 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { WAITLIST_NOTIFICATION_TYPES, WAITLIST_STATUS } from "../constants.js";
-import { normalizeEmail, platformActor, waitlistDb, waitlistExecutor } from "../lib.js";
+import { WAITLIST_NOTIFICATION_TYPES, WAITLIST_STATUS } from "../constants.ts";
+import { normalizeEmail, platformActor, waitlistDb, waitlistExecutor } from "../lib.ts";
 import {
   resolveWaitlistAdminMailLocale,
   resolveWaitlistMailLocale,
   waitlistAdminNoticeVariables,
   waitlistConfirmationVariables,
-} from "../mail.js";
+} from "../mail.ts";
 import {
   DEFAULT_SUBMIT_EMAIL_RATE_LIMITS,
   DEFAULT_SUBMIT_RATE_LIMIT,
   type WaitlistOptions,
-} from "../options.js";
-import { type WaitlistSubmitInput, WaitlistSubmitSchema } from "../payloads.js";
+} from "../options.ts";
+import { type WaitlistSubmitInput, WaitlistSubmitSchema } from "../payloads.ts";
 
 // pg_advisory_xact_lock namespace (int4): 'wlst' as ASCII, disjoint from the
 // framework's other fixed advisory-lock keys.

package/packages/bundled-features/src/waitlist/i18n.ts

@@ -28,6 +28,10 @@ export const WAITLIST_I18N: Readonly<Record<string, LocalizedString>> = {
     en: "Invited",
     de: "Eingeladen",
   },
+  "waitlist:entity:waitlistEntry:field:status:option:provisioned": {
+    en: "Provisioned",
+    de: "Eingerichtet",
+  },
   "waitlist:entity:waitlistEntry:field:status:option:rejected": {
     en: "Rejected",
     de: "Abgelehnt",

package/packages/bundled-features/src/waitlist/import.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { WaitlistStatus } from "./constants.ts";
+import { normalizeEmail, platformActor, waitlistExecutor } from "./lib.ts";
+
+export type WaitlistImportEntry = {
+  /** Stable identity of the source row (e.g. `offlot:<uuid>`); the new entry id derives from it. */
+  readonly sourceKey: string;
+  readonly name: string;
+  readonly email: string;
+  readonly locale: string;
+  readonly status: WaitlistStatus;
+  readonly submittedAt: Temporal.Instant;
+  readonly company?: string;
+  readonly portfolio?: string;
+  readonly message?: string;
+  readonly invitedAt?: Temporal.Instant;
+  readonly invitedBy?: string;
+  readonly provisionedAt?: Temporal.Instant;
+  readonly linkedTenantId?: string;
+};
+
+export type WaitlistImportOutcome = "created" | "skipped";
+
+// RFC 4122 name-based UUID (v5 layout, fixed namespace) so a re-run finds the entry
+// it created before without matching on encrypted personal data.
+const IMPORT_NAMESPACE = "kumiko-waitlist-import";
+
+export function waitlistImportId(sourceKey: string): string {
+  const bytes = createHash("sha1").update(`${IMPORT_NAMESPACE}:${sourceKey}`).digest();
+  const byte6 = bytes[6] ?? 0;
+  const byte8 = bytes[8] ?? 0;
+  bytes[6] = (byte6 & 0x0f) | 0x50;
+  bytes[8] = (byte8 & 0x3f) | 0x80;
+  const hex = bytes.subarray(0, 16).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+function presentOnly(fields: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+// Writes through the entity executor, so events, projection and subject encryption
+// behave exactly as for a live submit. No mail, no rate limit, no duplicate-by-email
+// check: the source row is the truth and the id makes the call idempotent.
+export async function importWaitlistEntry(
+  db: TenantDb,
+  entry: WaitlistImportEntry,
+  options: { readonly dryRun?: boolean } = {},
+): Promise<WaitlistImportOutcome> {
+  const id = waitlistImportId(entry.sourceKey);
+  const existing = await waitlistExecutor.detail({ id }, platformActor(), db);
+  if (existing) return "skipped";
+  if (options.dryRun === true) return "created";
+  const created = await waitlistExecutor.create(
+    {
+      id,
+      name: entry.name,
+      email: normalizeEmail(entry.email),
+      locale: entry.locale,
+      status: entry.status,
+      submittedAt: entry.submittedAt,
+      ...presentOnly({
+        company: entry.company,
+        portfolio: entry.portfolio,
+        message: entry.message,
+        invitedAt: entry.invitedAt,
+        invitedBy: entry.invitedBy,
+        provisionedAt: entry.provisionedAt,
+        linkedTenantId: entry.linkedTenantId,
+      }),
+    },
+    platformActor(),
+    db,
+  );
+  if (!created.isSuccess)
+    throw new InternalError({
+      message: `waitlist import failed for ${entry.sourceKey}: ${created.error.code}`,
+    });
+  return "created";
+}

package/packages/bundled-features/src/waitlist/index.ts

@@ -8,8 +8,26 @@ export {
   WaitlistHandlers,
   WaitlistQueries,
   type WaitlistStatus,
-} from "./constants.js";
-export { isOpenWaitlistStatus, waitlistEntryEntity, waitlistEntryTable } from "./entity.js";
-export { createWaitlistFeature } from "./feature.js";
-export type { WaitlistInviteOptions, WaitlistOptions } from "./options.js";
-export { type WaitlistSubmitInput, WaitlistSubmitSchema } from "./payloads.js";
+} from "./constants.ts";
+export { isOpenWaitlistStatus, waitlistEntryEntity, waitlistEntryTable } from "./entity.ts";
+export { createWaitlistFeature } from "./feature.ts";
+export {
+  importWaitlistEntry,
+  type WaitlistImportEntry,
+  type WaitlistImportOutcome,
+  waitlistImportId,
+} from "./import.ts";
+export {
+  DEFAULT_IMPORT_LOCALE,
+  DEFAULT_LEGACY_SOURCE_TABLE,
+  isLegacyWaitlistSource,
+  LEGACY_WAITLIST_SOURCES,
+  type LegacyWaitlistMigrateOptions,
+  type LegacyWaitlistMigrateReport,
+  type LegacyWaitlistSource,
+  migrateLegacyWaitlist,
+  offlotLegacyTable,
+  publicstatusLegacyTable,
+} from "./legacy-migrate.ts";
+export type { WaitlistInviteOptions, WaitlistOptions } from "./options.ts";
+export { type WaitlistSubmitInput, WaitlistSubmitSchema } from "./payloads.ts";

package/packages/bundled-features/src/waitlist/legacy-migrate.ts

@@ -0,0 +1,220 @@
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createTenantDb,
+  selectMany,
+  table,
+  text as textColumn,
+  timestamp,
+  transaction,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { DbConnection } from "@cosmicdrift/kumiko-types/db-connection";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { WAITLIST_STATUS, type WaitlistStatus } from "./constants.ts";
+import { importWaitlistEntry, type WaitlistImportEntry } from "./import.ts";
+
+export const LEGACY_WAITLIST_SOURCES = ["offlot", "publicstatus"] as const;
+export type LegacyWaitlistSource = (typeof LEGACY_WAITLIST_SOURCES)[number];
+
+export function isLegacyWaitlistSource(value: string | undefined): value is LegacyWaitlistSource {
+  return LEGACY_WAITLIST_SOURCES.some((known) => known === value);
+}
+
+export const DEFAULT_LEGACY_SOURCE_TABLE: Readonly<Record<LegacyWaitlistSource, string>> = {
+  offlot: "read_waitlist_entries",
+  publicstatus: "marketing_waitlist",
+};
+
+export const DEFAULT_IMPORT_LOCALE = "en";
+
+export type LegacyWaitlistMigrateOptions = {
+  readonly from: LegacyWaitlistSource;
+  readonly dryRun: boolean;
+  readonly sourceTable: string;
+  /** publicstatus rows carry no language; every imported entry gets this one. */
+  readonly defaultLocale: string;
+};
+
+export type LegacyWaitlistMigrateReport = {
+  readonly read: number;
+  readonly created: number;
+  readonly skipped: number;
+  readonly unreadable: number;
+};
+
+type LegacyRow = Readonly<Record<string, unknown>>;
+
+function toInstant(value: unknown): Temporal.Instant | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (value instanceof Temporal.Instant) return value;
+  if (value instanceof Date) return Temporal.Instant.fromEpochMilliseconds(Number(value));
+  if (typeof value !== "string") return undefined;
+  try {
+    return Temporal.Instant.from(value);
+  } catch {
+    // Temporal.Instant.from throws RangeError for a non-ISO string.
+    return undefined;
+  }
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function isWaitlistStatus(value: string | undefined): value is WaitlistStatus {
+  return Object.values(WAITLIST_STATUS).some((known) => known === value);
+}
+
+// Legacy offlot rows may hold subject ciphertext; decryption is self-describing and
+// needs the same KMS the app ran with. Without it the value cannot be read, so the
+// caller counts the row as unreadable instead of importing ciphertext as the name.
+async function readPii(value: unknown, field: string): Promise<string | undefined> {
+  const raw = nonEmpty(value);
+  if (raw === undefined || !isPiiCiphertext(raw)) return raw;
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return undefined;
+  const decrypted = await decryptPiiFieldValues({ [field]: raw }, [field], kms, {
+    requestId: "waitlist-migrate",
+  });
+  const plain = decrypted[field];
+  return typeof plain === "string" && plain !== PII_ERASED_SENTINEL ? plain : undefined;
+}
+
+// Source columns without a FW counterpart (city, stock, country, notes) are kept
+// as labelled lines in `message`, so no information is lost.
+function offlotMessage(row: LegacyRow): string | undefined {
+  const lines = [
+    ["City", nonEmpty(row["city"])],
+    ["Stock", nonEmpty(row["stock"])],
+    ["Country", nonEmpty(row["country"])],
+    ["Notes", nonEmpty(row["notes"])],
+  ].flatMap(([label, value]) => (value === undefined ? [] : [`${label}: ${value}`]));
+  return lines.length === 0 ? undefined : lines.join("\n");
+}
+
+export async function mapOfflotRow(row: LegacyRow): Promise<WaitlistImportEntry | undefined> {
+  const id = nonEmpty(row["id"]);
+  const name = await readPii(row["name"], "name");
+  const email = await readPii(row["email"], "email");
+  const submittedAt = toInstant(row["submittedAt"]);
+  const status = nonEmpty(row["status"]);
+  if (!id || !name || !email || !submittedAt || !isWaitlistStatus(status)) return undefined;
+  const company = nonEmpty(row["dealership"]);
+  const message = offlotMessage(row);
+  const invitedAt = toInstant(row["invitedAt"]);
+  const provisionedAt = toInstant(row["provisionedAt"]);
+  const invitedBy = nonEmpty(row["invitedBy"]);
+  const linkedTenantId = nonEmpty(row["linkedTenantId"]);
+  return {
+    sourceKey: `offlot:${id}`,
+    name,
+    email,
+    locale: nonEmpty(row["locale"]) ?? DEFAULT_IMPORT_LOCALE,
+    status,
+    submittedAt,
+    ...(company !== undefined && { company }),
+    ...(message !== undefined && { message }),
+    ...(invitedAt !== undefined && { invitedAt }),
+    ...(invitedBy !== undefined && { invitedBy }),
+    ...(provisionedAt !== undefined && { provisionedAt }),
+    ...(linkedTenantId !== undefined && { linkedTenantId }),
+  };
+}
+
+export function mapPublicstatusRow(
+  row: LegacyRow,
+  defaultLocale: string,
+): WaitlistImportEntry | undefined {
+  const id = nonEmpty(row["id"]);
+  const email = nonEmpty(row["email"]);
+  const submittedAt = toInstant(row["createdAt"]);
+  if (!id || !email || !submittedAt) return undefined;
+  return {
+    sourceKey: `publicstatus:${id}`,
+    // The apex form only asked for an address; the FW entry requires a name.
+    name: email.split("@")[0] ?? email,
+    email,
+    locale: defaultLocale,
+    status: WAITLIST_STATUS.Pending,
+    submittedAt,
+  };
+}
+
+export function publicstatusLegacyTable(sourceTable: string) {
+  return table(sourceTable, {
+    id: uuid("id").primaryKey(),
+    email: textColumn("email").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  });
+}
+
+export function offlotLegacyTable(sourceTable: string) {
+  return table(sourceTable, {
+    id: uuid("id").primaryKey(),
+    name: textColumn("name").notNull(),
+    email: textColumn("email").notNull(),
+    dealership: textColumn("dealership"),
+    city: textColumn("city"),
+    stock: textColumn("stock"),
+    country: textColumn("country"),
+    locale: textColumn("locale").notNull(),
+    status: textColumn("status").notNull(),
+    submittedAt: timestamp("submitted_at", { withTimezone: true }).notNull(),
+    invitedAt: timestamp("invited_at", { withTimezone: true }),
+    invitedBy: textColumn("invited_by"),
+    provisionedAt: timestamp("provisioned_at", { withTimezone: true }),
+    linkedTenantId: textColumn("linked_tenant_id"),
+    notes: textColumn("notes"),
+  });
+}
+
+async function readLegacyRows(
+  db: DbConnection,
+  from: LegacyWaitlistSource,
+  sourceTable: string,
+): Promise<readonly LegacyRow[]> {
+  if (from === "publicstatus") {
+    return await selectMany<LegacyRow>(db, publicstatusLegacyTable(sourceTable), undefined, {
+      orderBy: { col: "createdAt", direction: "asc" },
+    });
+  }
+  return await selectMany<LegacyRow>(db, offlotLegacyTable(sourceTable), undefined, {
+    orderBy: { col: "submittedAt", direction: "asc" },
+  });
+}
+
+// Idempotent: the new entry id derives from the source row id, so a re-run finds
+// what an earlier run wrote and skips it. Writes go through the waitlist entity
+// executor (events, projection, subject encryption), never into tables directly.
+export async function migrateLegacyWaitlist(
+  db: DbConnection,
+  options: LegacyWaitlistMigrateOptions,
+): Promise<LegacyWaitlistMigrateReport> {
+  const rows = await readLegacyRows(db, options.from, options.sourceTable);
+  let created = 0;
+  let skipped = 0;
+  let unreadable = 0;
+  for (const row of rows) {
+    const entry =
+      options.from === "offlot"
+        ? await mapOfflotRow(row)
+        : mapPublicstatusRow(row, options.defaultLocale);
+    if (!entry) {
+      unreadable += 1;
+      continue;
+    }
+    await transaction(db, async (tx) => {
+      const tenantDb = createTenantDb({ db: tx, tenantId: SYSTEM_TENANT_ID, mode: "system" });
+      const outcome = await importWaitlistEntry(tenantDb, entry, { dryRun: options.dryRun });
+      if (outcome === "created") created += 1;
+      else skipped += 1;
+    });
+  }
+  return { read: rows.length, created, skipped, unreadable };
+}

package/packages/bundled-features/src/waitlist/lib.ts

@@ -4,17 +4,17 @@ import {
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
+  type AppContext,
   access,
   createSystemUser,
-  type HandlerContext,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { tenantMembershipsTable } from "../tenant/index.js";
-import { userTable } from "../user/index.js";
-import { waitlistEntryEntity, waitlistEntryTable } from "./entity.js";
+import { tenantMembershipsTable } from "../tenant/index.ts";
+import { userTable } from "../user/index.ts";
+import { waitlistEntryEntity, waitlistEntryTable } from "./entity.ts";
 
 export const WAITLIST_CROSS_TENANT_REASON = "waitlist is platform-wide (systemScope)";
 
@@ -28,7 +28,7 @@ export function normalizeEmail(email: string): string {
   return email.toLowerCase();
 }
 
-export function waitlistDb(ctx: HandlerContext): TenantDb {
+export function waitlistDb(ctx: Pick<AppContext, "systemDb">): TenantDb {
   if (!ctx.systemDb) {
     throw new InternalError({
       message: "waitlist requires ctx.systemDb — is r.systemScope() set on the feature?",

package/packages/bundled-features/src/waitlist/link-on-signup.ts

@@ -0,0 +1,106 @@
+import {
+  createTenantDb,
+  entityEventName,
+  fetchOne,
+  selectMany,
+} from "@cosmicdrift/kumiko-framework/db";
+import { type MultiStreamApplyFn, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { decryptStoredPii } from "../shared/index.ts";
+import { tenantMembershipsTable } from "../tenant/index.ts";
+import { userTable } from "../user/index.ts";
+import { DEFAULT_OWN_TENANT_INVITE_ROLE, WAITLIST_STATUS } from "./constants.ts";
+import { normalizeEmail, platformActor, waitlistExecutor } from "./lib.ts";
+
+const PII_DECRYPT_REASON = "waitlist:link-on-signup";
+
+export const WAITLIST_MEMBERSHIP_CREATED_EVENT = entityEventName("tenant-membership", "created");
+
+type SignupOwnerMembership = { readonly userId: string; readonly tenantId: string };
+
+// Only a TenantAdmin membership can be the signup owner; invite-accept memberships of
+// other roles are not owners.
+function readSignupOwnerMembership(
+  event: Parameters<MultiStreamApplyFn>[0],
+): SignupOwnerMembership | undefined {
+  const { userId, roles } = event.payload;
+  if (typeof userId !== "string") return undefined;
+  if (!parseRoles(roles).includes(DEFAULT_OWN_TENANT_INVITE_ROLE)) return undefined;
+  return { userId, tenantId: event.tenantId };
+}
+
+// An unreadable submittedAt sorts last instead of throwing: one bad row must not
+// stall the at-least-once consumer.
+function newestSubmittedFirst(a: Record<string, unknown>, b: Record<string, unknown>): number {
+  return submittedAtMillis(b) - submittedAtMillis(a);
+}
+
+function submittedAtMillis(row: Record<string, unknown>): number {
+  return instantMillis(row["submittedAt"]);
+}
+
+function instantMillis(value: unknown): number {
+  if (value instanceof Temporal.Instant) return value.epochMilliseconds;
+  if (typeof value !== "string") return 0;
+  try {
+    return Temporal.Instant.from(value).epochMilliseconds;
+  } catch {
+    // Temporal.Instant.from throws RangeError for a non-ISO string.
+    return 0;
+  }
+}
+
+// Runs as a multi-stream consumer (at least once): the hook phase of the signup and
+// invite-accept paths has no system db handle, and a waitlist problem must not roll
+// back the signup. Idempotent because only `invited` entries are updated.
+export const linkWaitlistOnSignup: MultiStreamApplyFn = async (event, tx) => {
+  const membership = readSignupOwnerMembership(event);
+  // skip: not a TenantAdmin membership, nothing to link.
+  if (!membership) return;
+
+  // Only the tenant's first membership is the owner; later TenantAdmin invites must not link.
+  const [first] = await selectMany<{ readonly id: string }>(
+    tx,
+    tenantMembershipsTable,
+    { tenantId: membership.tenantId },
+    { limit: 1, fields: ["id"], orderBy: [{ col: "insertedAt" }, { col: "id" }] },
+  );
+  // skip: another membership came first.
+  if (first && first.id !== event.aggregateId) return;
+
+  const db = createTenantDb({ db: tx, tenantId: SYSTEM_TENANT_ID, mode: "system" });
+  const user = await fetchOne<{ email?: unknown }>(tx, userTable, { id: membership.userId });
+  // skip: user row unreadable (erased or not projected yet).
+  if (typeof user?.email !== "string") return;
+  const email = normalizeEmail(await decryptStoredPii(user.email, "email", PII_DECRYPT_REASON));
+
+  const found = await waitlistExecutor.list(
+    {
+      filter: { field: "email", op: "eq", value: email },
+      filters: [{ field: "status", op: "in", value: [WAITLIST_STATUS.Invited] }],
+    },
+    platformActor(),
+    db,
+  );
+  const invited = [...found.rows].sort(newestSubmittedFirst)[0];
+  // skip: the signup email has no invited waitlist entry (open signup or stale invite).
+  if (!invited) return;
+  const { id, version } = invited;
+  // skip: defensive guard on the row shape.
+  if (typeof id !== "string" || typeof version !== "number") return;
+
+  await waitlistExecutor.update(
+    {
+      id,
+      version,
+      changes: {
+        status: WAITLIST_STATUS.Provisioned,
+        linkedTenantId: membership.tenantId,
+        provisionedAt: Temporal.Now.instant(),
+      },
+    },
+    platformActor(),
+    db,
+  );
+};

package/packages/bundled-features/src/waitlist/mail.ts

@@ -4,7 +4,7 @@ import {
   type TemplateVariables,
   templateVariable,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { mailHeading, mailParagraph, mailRepeatedRows } from "../shared/index.js";
+import { mailHeading, mailParagraph, mailRepeatedRows } from "../shared/index.ts";
 
 export type WaitlistMailLocale = "en" | "de" | "es";