@cosmicdrift/kumiko-samples 0.338.0 → 0.339.0

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -12,6 +12,7 @@
 
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants.js";
+import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.js";
 
 // Aggregate-type für den event-store. Eine subscription pro Tenant ist
 // ein stream; der subscriptionAggregateId-helper liefert die stream-id.
@@ -196,6 +197,23 @@ export type ContractTerminationRequestedPayload = z.infer<
   typeof contractTerminationRequestedPayloadSchema
 >;
 
+// A public declaration matched to this tenant. The provider cancel runs in a
+// job triggered by this event, so the request itself only looks up and appends.
+export const CONTRACT_TERMINATION_DECLARED_EVENT_SHORT = "contract-termination-declared" as const;
+export const CONTRACT_TERMINATION_DECLARED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_DECLARED_EVENT_SHORT}` as const;
+
+export const contractTerminationDeclaredPayloadSchema = z.object({
+  requestId: z.string().min(1).max(100),
+  declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+  terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+  receivedAtIso: z.string().min(1),
+  locale: z.enum(CONSENT_LOCALES),
+});
+export type ContractTerminationDeclaredPayload = z.infer<
+  typeof contractTerminationDeclaredPayloadSchema
+>;
+
 export const CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE =
   "contract-termination-unmatched" as const;
 export const CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT = "contract-termination-unmatched" as const;

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -64,7 +64,7 @@ export function createCheckoutSessionHandler(
 ): WriteHandlerDef {
   const consumerProtection = options.consumerProtection;
   const schema = consumerProtection
-    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema })
+    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() })
     : createCheckoutSessionSchema;
   return {
     name: "create-checkout-session",
@@ -79,10 +79,9 @@ export function createCheckoutSessionHandler(
       const payload = event.payload as CreateCheckoutSessionPayload;
 
       const mode = payload.mode ?? "subscription";
-      const consent =
-        consumerProtection && payload.consent
-          ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
-          : undefined;
+      const consent = consumerProtection
+        ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
+        : undefined;
 
       const result = await openCheckout(
         ctx,

package/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts

@@ -35,7 +35,9 @@ export function createStartPlanCheckoutHandler(
   const consumerProtection = options.consumerProtection;
   const tierSchema = z.object({ tier: z.enum(plans) });
   const schema = (
-    consumerProtection ? tierSchema.extend({ consent: consentPayloadSchema }) : tierSchema
+    consumerProtection
+      ? tierSchema.extend({ consent: consentPayloadSchema.optional() })
+      : tierSchema
   ).strict();
 
   return {
@@ -65,10 +67,9 @@ export function createStartPlanCheckoutHandler(
         });
       }
 
-      const consent =
-        consumerProtection && payload.consent
-          ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
-          : undefined;
+      const consent = consumerProtection
+        ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
+        : undefined;
 
       const baseUrl = options.baseUrl ?? "";
       const result = await openCheckout(

package/packages/bundled-features/src/billing-foundation/i18n.ts

@@ -124,6 +124,9 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.priceUnavailable": {
     en: "This plan's price is temporarily unavailable.",
   },
+  "billing-foundation.errors.consentRequired": {
+    en: "Confirm both consent boxes before you continue.",
+  },
   "billing-foundation.errors.consentTextOutdated": {
     en: "The consent text has changed. Reload the page and confirm again.",
   },

package/packages/bundled-features/src/billing-foundation/tenant-destroy-hook.ts

@@ -26,7 +26,7 @@ export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON =
 export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
   declareEscapeHatch({ reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON),
+    db: ctx.db.unsafeRaw(),
     tenantId: ctx.tenantId,
   });
   const aggregateId = subscriptionAggregateId(ctx.tenantId);
@@ -39,7 +39,7 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
   } else {
     await ctx.db.deleteMany(subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
   }
-  await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
+  await archiveStream(ctx.db.unsafeRaw(), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
@@ -56,7 +56,7 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
 export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {
   declareEscapeHatch({ reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON });
   const { profile } = await resolveProfileForTenant({
-    db: ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON),
+    db: ctx.db.unsafeRaw(),
     tenantId: ctx.tenantId,
   });
   const aggregateId = paymentAggregateId(ctx.tenantId);
@@ -71,7 +71,7 @@ export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<
       tenantId: ctx.tenantId,
     });
   }
-  await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
+  await archiveStream(ctx.db.unsafeRaw(), {
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: PAYMENT_AGGREGATE_TYPE,

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -35,6 +35,7 @@ import {
   type SubscriptionCancelTiming,
   type SubscriptionEventType,
   type SubscriptionStatus,
+  type TerminationScope,
 } from "./constants.js";
 
 // =============================================================================
@@ -389,6 +390,11 @@ export type ConsumerProtectionOptions = {
   /** Per-locale VAT note; must carry at least `de` and `en`. */
   readonly vatNote: Readonly<Record<string, string>>;
   readonly operatorEmail: string;
+  /** Where the public § 312k declaration is reachable. `"tenant-host"`
+   *  (default): on a host that resolves a tenant. `"platform"`: also on a
+   *  host that resolves none (the platform apex) — the declaration then runs
+   *  without a request tenant and finds the contract by the declarant's email. */
+  readonly terminationScope?: TerminationScope;
   /** Root-relative paths or absolute https URLs. */
   readonly legalLinks: {
     readonly terms: string;

package/packages/bundled-features/src/billing-foundation/validate-options.ts

@@ -4,6 +4,7 @@
 // re-exported from index.ts.
 
 import * as z from "zod";
+import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
 import type { BillingFoundationOptions, ConsumerProtectionOptions } from "./types.js";
 
 function isRootRelativePath(path: string): boolean {
@@ -35,6 +36,11 @@ function validateConsumerProtection(cp: ConsumerProtectionOptions): void {
       `createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`,
     );
   }
+  if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
+    throw new Error(
+      `createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`,
+    );
+  }
   for (const [key, link] of Object.entries(cp.legalLinks)) {
     if (!isRootRelativeOrHttpsUrl(link)) {
       throw new Error(

package/packages/bundled-features/src/channel-discord/discord-channel.ts

@@ -0,0 +1,32 @@
+import {
+  type ChatWebhookChannelOptions,
+  chatMessageText,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+  truncateChars,
+} from "../delivery/index.js";
+
+export type DiscordChannelOptions = ChatWebhookChannelOptions;
+
+export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"] as const;
+export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";
+export const DISCORD_CONTENT_MAX_CHARS = 2000;
+
+export function createDiscordChannel(
+  options: DiscordChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "discord",
+    featureName: "channel-discord",
+    defaultAllowedHosts: DISCORD_DEFAULT_ALLOWED_HOSTS,
+    requiredPathPrefix: DISCORD_WEBHOOK_PATH_PREFIX,
+    keyFor,
+    // parse: [] keeps @everyone / @here / role and user mentions in the text inert.
+    buildBody: (message) => ({
+      content: truncateChars(chatMessageText(message), DISCORD_CONTENT_MAX_CHARS),
+      allowed_mentions: { parse: [] },
+    }),
+    options,
+  });
+}

package/packages/bundled-features/src/channel-discord/feature.ts

@@ -0,0 +1,40 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+
+export function createChannelDiscordFeature(
+  options: DiscordChannelOptions = {},
+): FeatureDefinition {
+  return defineFeature("channel-discord", (r) => {
+    r.describe(
+      'Posts delivery notifications to a Discord webhook, registered as the `discord` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { discord: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-discord:webhooks.<connection name>`; only the connection name is logged. Mentions are disabled and content is cut to 2000 characters. Requires `delivery` and `secrets`. Host allowlist (discord.com, discordapp.com, path /api/webhooks/), https-only and the request timeout are app options of `createChannelDiscordFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Discord Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: { en: "Discord webhooks", de: "Discord-Webhooks", es: "Webhooks de Discord" },
+      hint: {
+        en: 'One secret per connection name; the value is the Discord webhook URL. Address it with route: { discord: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Discord-Webhook-URL. Adressierung mit route: { discord: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Discord. Se usa con route: { discord: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createDiscordChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "discord", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

package/packages/bundled-features/src/channel-discord/index.ts

@@ -0,0 +1,2 @@
+export { createDiscordChannel, type DiscordChannelOptions } from "./discord-channel.js";
+export { createChannelDiscordFeature } from "./feature.js";

package/packages/bundled-features/src/channel-slack/feature.ts

@@ -0,0 +1,38 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";
+
+export function createChannelSlackFeature(options: SlackChannelOptions = {}): FeatureDefinition {
+  return defineFeature("channel-slack", (r) => {
+    r.describe(
+      'Posts delivery notifications to a Slack incoming webhook, registered as the `slack` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { slack: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-slack:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (hooks.slack.com), https-only and the request timeout are app options of `createChannelSlackFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Slack Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: { en: "Slack webhooks", de: "Slack-Webhooks", es: "Webhooks de Slack" },
+      hint: {
+        en: 'One secret per connection name; the value is the Slack webhook URL. Address it with route: { slack: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Slack-Webhook-URL. Adressierung mit route: { slack: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Slack. Se usa con route: { slack: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createSlackChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "slack", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

package/packages/bundled-features/src/channel-slack/index.ts

@@ -0,0 +1,2 @@
+export { createChannelSlackFeature } from "./feature.js";
+export { createSlackChannel, type SlackChannelOptions } from "./slack-channel.js";

package/packages/bundled-features/src/channel-slack/slack-channel.ts

@@ -0,0 +1,29 @@
+import {
+  type ChatWebhookChannelOptions,
+  chatMessageText,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+} from "../delivery/index.js";
+
+export type SlackChannelOptions = ChatWebhookChannelOptions;
+
+export const SLACK_DEFAULT_ALLOWED_HOSTS = ["hooks.slack.com"] as const;
+
+// Slack mrkdwn treats & < > as control characters (links, @-mentions via <!channel>).
+export function escapeSlackText(text: string): string {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function createSlackChannel(
+  options: SlackChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "slack",
+    featureName: "channel-slack",
+    defaultAllowedHosts: SLACK_DEFAULT_ALLOWED_HOSTS,
+    keyFor,
+    buildBody: (message) => ({ text: escapeSlackText(chatMessageText(message)) }),
+    options,
+  });
+}

package/packages/bundled-features/src/channel-teams/feature.ts

@@ -0,0 +1,42 @@
+import {
+  chatConnectionNameSchema,
+  DELIVERY_CHANNEL_EXTENSION,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";
+
+export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): FeatureDefinition {
+  return defineFeature("channel-teams", (r) => {
+    r.describe(
+      'Posts delivery notifications to a Microsoft Teams webhook (Workflows or connector) as an Adaptive Card, registered as the `teams` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { teams: "<connection name>" } })`. The webhook URL is a tenant secret under `channel-teams:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (.webhook.office.com, .logic.azure.com, .powerplatform.com), https-only and the request timeout are app options of `createChannelTeamsFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Microsoft Teams Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const webhooks = r.secretNamespace("webhooks", {
+      label: {
+        en: "Microsoft Teams webhooks",
+        de: "Microsoft Teams-Webhooks",
+        es: "Webhooks de Microsoft Teams",
+      },
+      hint: {
+        en: 'One secret per connection name; the value is the Microsoft Teams webhook URL. Address it with route: { teams: "<connection name>" }.',
+        de: 'Ein Secret pro Verbindungsname; der Wert ist die Microsoft Teams-Webhook-URL. Adressierung mit route: { teams: "<Verbindungsname>" }.',
+        es: 'Un secreto por nombre de conexión; el valor es la URL del webhook de Microsoft Teams. Se usa con route: { teams: "<nombre de conexión>" }.',
+      },
+      scope: "tenant",
+      nameSchema: chatConnectionNameSchema,
+    });
+
+    const channel = createTeamsChannel(options, webhooks.keyFor);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

package/packages/bundled-features/src/channel-teams/index.ts

@@ -0,0 +1,2 @@
+export { createChannelTeamsFeature } from "./feature.js";
+export { createTeamsChannel, type TeamsChannelOptions } from "./teams-channel.js";

package/packages/bundled-features/src/channel-teams/teams-channel.ts

@@ -0,0 +1,50 @@
+import {
+  type ChatWebhookChannelOptions,
+  createChatWebhookChannel,
+  type DeliveryChannel,
+} from "../delivery/index.js";
+
+export type TeamsChannelOptions = ChatWebhookChannelOptions;
+
+export const TEAMS_DEFAULT_ALLOWED_HOSTS = [
+  ".webhook.office.com",
+  ".logic.azure.com",
+  ".powerplatform.com",
+] as const;
+
+// Text only ever goes into TextBlocks (no markup interpretation of titles/bodies
+// beyond Adaptive Card's own text rendering).
+export function buildTeamsAdaptiveCard(title: string, body: string | undefined): unknown {
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        contentUrl: null,
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [
+            { type: "TextBlock", text: title, weight: "Bolder", wrap: true },
+            ...(body ? [{ type: "TextBlock", text: body, wrap: true }] : []),
+          ],
+        },
+      },
+    ],
+  };
+}
+
+export function createTeamsChannel(
+  options: TeamsChannelOptions,
+  keyFor: (connection: string) => string,
+): DeliveryChannel {
+  return createChatWebhookChannel({
+    name: "teams",
+    featureName: "channel-teams",
+    defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS,
+    keyFor,
+    buildBody: (message) => buildTeamsAdaptiveCard(message.title, message.body),
+    options,
+  });
+}

package/packages/bundled-features/src/channel-telegram/feature.ts

@@ -0,0 +1,35 @@
+import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";
+
+export function createChannelTelegramFeature(
+  options: TelegramChannelOptions = {},
+): FeatureDefinition {
+  return defineFeature("channel-telegram", (r) => {
+    r.describe(
+      'Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: "<chat id or @channel>" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL and request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.',
+    );
+    r.uiHints({
+      displayLabel: "Telegram Channel",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("delivery");
+    r.requires("secrets");
+
+    const botToken = r.secret("botToken", {
+      label: { en: "Telegram bot token" },
+      hint: {
+        en: 'Token from @BotFather. Used for every Telegram chat the tenant addresses via route: { telegram: "<chat id>" }.',
+      },
+      redact: () => "••••••••",
+      scope: "tenant",
+    });
+
+    const channel = createTelegramChannel(options, botToken.name);
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "telegram", {
+      mode: channel.mode,
+      send: channel.send,
+    });
+  });
+}

package/packages/bundled-features/src/channel-telegram/index.ts

@@ -0,0 +1,2 @@
+export { createChannelTelegramFeature } from "./feature.js";
+export { createTelegramChannel, type TelegramChannelOptions } from "./telegram-channel.js";

package/packages/bundled-features/src/channel-telegram/telegram-channel.ts

@@ -0,0 +1,74 @@
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import {
+  chatMessageText,
+  DEFAULT_CHAT_TIMEOUT_MS,
+  type DeliveryChannel,
+  postChatWebhook,
+  toChannelResult,
+  truncateChars,
+} from "../delivery/index.js";
+
+export type TelegramChannelOptions = {
+  // App-level override (tests, self-hosted Bot API server); never tenant config.
+  readonly apiBaseUrl?: string;
+  readonly timeoutMs?: number;
+};
+
+export const TELEGRAM_DEFAULT_API_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_TEXT_MAX_CHARS = 4096;
+
+// Numeric chat/group id (groups and channels are negative) or a public @channelname.
+const TELEGRAM_CHAT_ID_PATTERN = /^(-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{3,31})$/;
+// `<bot id>:<secret>`; the token is spliced into the URL path, so only the real shape passes.
+const TELEGRAM_BOT_TOKEN_PATTERN = /^\d{1,20}:[A-Za-z0-9_-]{10,}$/;
+
+export function createTelegramChannel(
+  options: TelegramChannelOptions,
+  botTokenKey: string,
+): DeliveryChannel {
+  const apiBaseUrl = options.apiBaseUrl ?? TELEGRAM_DEFAULT_API_BASE_URL;
+
+  return {
+    name: "telegram",
+    mode: "queued",
+
+    async send(address, message, ctx) {
+      if (!TELEGRAM_CHAT_ID_PATTERN.test(address)) {
+        return toChannelResult(address, { ok: false, code: "invalid_address" });
+      }
+      let token: string | undefined;
+      try {
+        const revealed = await ctx.secrets?.get(ctx.tenantId, botTokenKey, {
+          userId: SYSTEM_USER_ID,
+          handlerName: "channel-telegram:send",
+        });
+        token = revealed?.reveal();
+      } catch {
+        token = undefined;
+      }
+      if (!token || !TELEGRAM_BOT_TOKEN_PATTERN.test(token)) {
+        return toChannelResult(address, { ok: false, code: "missing_credentials" });
+      }
+
+      // The base URL is the allowlist: only its own host is reachable.
+      let baseHost: string;
+      try {
+        baseHost = new URL(apiBaseUrl).hostname;
+      } catch {
+        return toChannelResult(address, { ok: false, code: "host_not_allowed" });
+      }
+      const result = await postChatWebhook({
+        url: `${apiBaseUrl.replace(/\/+$/, "")}/bot${token}/sendMessage`,
+        allowedHosts: [baseHost],
+        requireHttps: apiBaseUrl.startsWith("https:"),
+        timeoutMs: options.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS,
+        // No parse_mode: Telegram renders the text literally.
+        body: {
+          chat_id: address,
+          text: truncateChars(chatMessageText(message), TELEGRAM_TEXT_MAX_CHARS),
+        },
+      });
+      return toChannelResult(address, result);
+    },
+  };
+}

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -334,9 +334,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     const subjectKey = subjectIdToKey(subject);
 
     const tenantScopeDenial = await resolveTenantScopeDenial(
-      ctx.db.unsafeRaw(
-        "tenant-scope check runs against the subject's tenant, not necessarily the caller's",
-      ),
+      ctx.db.unsafeRaw(),
       ctx.registry.features,
       event.user,
       raw,
@@ -348,9 +346,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         denialReasonOf(tenantScopeDenial),
-        ctx.dbOutsideTransaction?.unsafeRaw(
-          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
-        ),
+        ctx.dbOutsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? tenantScopeDenial;
     }
@@ -358,9 +354,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     // Runs after the tenant gate but before any key is touched: a retention
     // check ahead of the tenant gate would leak a foreign entity's retention
     // posture to a cross-tenant prober.
-    const retentionDenial = await resolveRetentionDenial(ctx, raw, () =>
-      ctx.db.unsafeRaw("retention check reads the record row's owning tenant, not the caller's"),
-    );
+    const retentionDenial = await resolveRetentionDenial(ctx, raw, () => ctx.db.unsafeRaw());
     if (retentionDenial) {
       const auditFailure = await appendDenialAuditEvent(
         ctx,
@@ -368,9 +362,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         TARGET_RECORD_RETENTION_BLOCK_DELETE,
-        ctx.dbOutsideTransaction?.unsafeRaw(
-          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
-        ),
+        ctx.dbOutsideTransaction?.unsafeRaw(),
       );
       return auditFailure ?? retentionDenial;
     }
@@ -387,9 +379,7 @@ export const forgetSubjectWrite = defineWriteHandler({
 
     // Blind-index sweep (#818): nulls bidx columns now so the deterministic
     // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
-    const crossTenantSubjectRunner = ctx.db.unsafeRaw(
-      "blind-index sweep and search purge address the subject across tenants",
-    );
+    const crossTenantSubjectRunner = ctx.db.unsafeRaw();
     await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
 
     // Derived search index still holds plaintext (#1610) — purge next to the
@@ -425,9 +415,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     // update is best-effort for real users.
     if (raw.kind === "user" && ctx.registry.features.has("user")) {
       try {
-        const userLifecycleRunner = ctx.db.unsafeRaw(
-          "user lifecycle update and PAT revoke run on the SYSTEM user stream",
-        );
+        const userLifecycleRunner = ctx.db.unsafeRaw();
         await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
         if (ctx.registry.features.has("personal-access-tokens")) {
           await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);

package/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -40,7 +40,7 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 
     const accessCheck = await checkFieldAccessForWrite(
-      ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON),
+      ctx.db.unsafeRaw(),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/packages/bundled-features/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -74,10 +74,7 @@ export function createDefineTenantFieldHandler(
       }
 
       if (limit !== undefined) {
-        const current = await countTenantFieldDefinitions(
-          ctx.db.unsafeRaw(DEFINE_TENANT_FIELD_REASON),
-          tenantId,
-        );
+        const current = await countTenantFieldDefinitions(ctx.db.unsafeRaw(), tenantId);
         if (current >= limit) {
           return failUnprocessable("cap_exceeded", {
             capName: "customFields.fieldDefinition.count",

package/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -63,7 +63,7 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
 
     const loaded = await loadFieldDefinition(
-      ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON),
+      ctx.db.unsafeRaw(),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/packages/bundled-features/src/custom-fields/wire-user-data-rights.ts

@@ -73,7 +73,7 @@ export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<
   // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar API, not a React hook.
   r.useExtension(EXT_USER_DATA, opts.entityName, {
     export: async (ctx: UserDataHookCtx) =>
-      exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+      exportCustomFields(ctx.db.unsafeRaw(), ctx, tableName, opts),
     escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
   });
 }