@openlup/platform 0.15.0 → 0.17.0

package/src/communications/contracts/subscriptionRenewalUpcoming.ts

@@ -0,0 +1,103 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionRenewalUpcomingCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionRenewalUpcomingEmailVars {
+  firstName: string | null;
+  /** Pre-formatted renewal CHARGE date (locale-formatted by the worker). */
+  renewalDateLabel: string | null;
+  /** Pre-formatted estimated delivery window, or null when unavailable. */
+  deliveryWindowLabel?: string | null;
+  /** Localized holiday caveat; present ONLY when a holiday moved the window. */
+  holidayNote?: string | null;
+  /**
+   * Pre-formatted composition edit deadline. Null when unknown OR when the
+   * deadline has already passed at send time — see the module header.
+   */
+  editCutoffLabel?: string | null;
+  /** Formatted gross amount of the upcoming charge, e.g. "129,99 zł", or null. */
+  amountLabel: string | null;
+  /**
+   * Starter-pack acquisition stage of the delivery being announced, or null for
+   * an ordinary renewal. `"graduation"` means the NEXT delivery switches to the
+   * steady package — a size and rhythm change the customer agreed to at checkout
+   * but has not seen since, so it gets its own paragraph rather than a detail
+   * line. `"delivery2"` only marks the discounted repeat; its amount already
+   * rides on `amountLabel`.
+   */
+  starterStage?: "delivery2" | "graduation" | null;
+  /** Units per delivery from the graduation on; renders only with `"graduation"`. */
+  starterSteadyUnitCount?: number | null;
+  /** Days between deliveries from the graduation on; renders only with `"graduation"`. */
+  starterSteadyCadenceDays?: number | null;
+  /** Adopter-formatted steady package, already localized; renders only with `"graduation"`. */
+  starterSteadyDetail?: string | null;
+  /** Absolute "manage subscription" URL; null/absent → no button. */
+  ctaUrl?: string | null;
+  /** Optional consumer context label; absent/null uses the selected pack's fallback. */
+  contextName?: string | null;
+}
+
+export interface SubscriptionRenewalUpcomingEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionRenewalUpcomingContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "renewalUpcoming">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionRenewalUpcomingEmailContent(
+    locale: Locale,
+    vars: SubscriptionRenewalUpcomingEmailVars,
+    signoff: string,
+  ): SubscriptionRenewalUpcomingEmailContent {
+    const copy: SubscriptionRenewalUpcomingCopy = subscriptionEmailContent.renewalUpcoming[locale];
+    const details: string[] = [
+      vars.renewalDateLabel ? copy.dateLine(vars.renewalDateLabel) : copy.noDateLine,
+    ];
+    if (vars.deliveryWindowLabel) details.push(copy.deliveryLine(vars.deliveryWindowLabel));
+    if (vars.holidayNote) details.push(vars.holidayNote);
+    if (vars.amountLabel) details.push(copy.amountLine(vars.amountLabel));
+    // Null when already past — the caller, not this renderer, owns that decision.
+    if (vars.editCutoffLabel) details.push(copy.editCutoffLine(vars.editCutoffLabel));
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.contextName ?? null)),
+      accentBox(details, { label: copy.detailsLabel }),
+    ];
+
+    // The package-size change is the one thing in this email a customer could be
+    // surprised by, so it gets its own paragraph ABOVE the generic self-service
+    // line, and it names moving the delivery first.
+    if (vars.starterStage === "graduation" && vars.starterSteadyUnitCount && vars.starterSteadyCadenceDays) {
+      blocks.push(paragraph(copy.starterGraduationLine(vars.starterSteadyUnitCount, vars.starterSteadyCadenceDays, vars.starterSteadyDetail)));
+    }
+    blocks.push(paragraph(copy.manageLine));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionRenewalUpcomingEmailContent };
+}

package/src/communications/contracts/subscriptionResumed.ts

@@ -0,0 +1,60 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionResumedEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Absolute CTA URL (manage subscription); null/absent → no button. */
+  ctaUrl?: string | null;
+  /** Optional consumer context label; absent/null uses the selected pack's fallback. */
+  contextName?: string | null;
+}
+
+export interface SubscriptionResumedEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionResumedContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "resumed">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionResumedEmailContent(
+    locale: Locale,
+    vars: SubscriptionResumedEmailVars,
+    signoff: string,
+  ): SubscriptionResumedEmailContent {
+    const copy = subscriptionEmailContent.resumed[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro(vars.contextName ?? null)),
+      accentBox(copy.reassurance(vars.brandName)),
+    ];
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionResumedEmailContent };
+}

package/src/communications/contracts/subscriptionWelcome.ts

@@ -0,0 +1,102 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionWelcomeCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionWelcomeEmailVars {
+  firstName: string | null;
+  cadenceDays: number | null;
+  /** Pre-formatted renewal CHARGE date (locale-formatted by the handler), or null. */
+  chargeDateLabel: string | null;
+  /** Pre-formatted estimated delivery window, e.g. "04.08.2026 – 05.08.2026", or null. */
+  deliveryWindowLabel: string | null;
+  /** Pre-formatted composition edit deadline, or null when unknown/already passed. */
+  editCutoffLabel?: string | null;
+  /**
+   * Localized holiday caveat, supplied by the handler ONLY when a public holiday
+   * actually moved the estimated window. Null/absent is the normal case and must
+   * render nothing — a standing "we account for holidays" line is noise.
+   */
+  holidayNote?: string | null;
+  /** Absolute "manage subscription" URL; null/absent → no button. */
+  ctaUrl?: string | null;
+  /**
+   * Starter-pack acquisition facts, present only for a subscription that carries
+   * an acquisition marker. `starterAmountLabel` is the DELIVERY-2 amount — the
+   * discounted repeat that lands on the date already stated above — and the
+   * steady pair describes what delivery 3 onwards looks like. The whole block is
+   * dropped when any of it is unknown; a half-stated plan is worse than none.
+   */
+  starterAmountLabel?: string | null;
+  starterSteadyUnitCount?: number | null;
+  starterSteadyCadenceDays?: number | null;
+  /** Adopter-formatted steady package, already localized; the steady line's third argument. */
+  starterSteadyDetail?: string | null;
+}
+
+export interface SubscriptionWelcomeEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWelcomeContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "welcome">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionWelcomeEmailContent(
+    locale: Locale,
+    vars: SubscriptionWelcomeEmailVars,
+    signoff: string,
+  ): SubscriptionWelcomeEmailContent {
+    const copy: SubscriptionWelcomeCopy = subscriptionEmailContent.welcome[locale];
+    const details: string[] = [];
+    if (vars.cadenceDays && vars.cadenceDays > 0) details.push(copy.cadenceLine(vars.cadenceDays));
+    // Both labels are derived from the same `next_cycle_at`, so they are present or
+    // absent together; the fallback keeps the pre-existing "we'll confirm" promise.
+    details.push(
+      vars.chargeDateLabel && vars.deliveryWindowLabel
+        ? copy.deliveryLine(vars.deliveryWindowLabel, vars.chargeDateLabel)
+        : copy.fallbackLine,
+    );
+    if (vars.holidayNote) details.push(vars.holidayNote);
+    // Acquisition plan: the delivery-2 amount and the steady rhythm, stated once at
+    // the only moment the customer is actually reading about their plan.
+    if (vars.starterAmountLabel) details.push(copy.starterDelivery2Line(vars.starterAmountLabel));
+    if (vars.starterSteadyUnitCount && vars.starterSteadyCadenceDays) {
+      details.push(copy.starterSteadyLine(vars.starterSteadyUnitCount, vars.starterSteadyCadenceDays, vars.starterSteadyDetail));
+    }
+    if (vars.editCutoffLabel) details.push(copy.editCutoffLine(vars.editCutoffLabel));
+
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+      accentBox(details, { label: copy.detailsLabel }),
+    ];
+
+    blocks.push(paragraph(copy.manageLine));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionWelcomeEmailContent };
+}

package/src/communications/contracts/subscriptionWinback.ts

@@ -0,0 +1,62 @@
+import type { SubscriptionEmailContent } from "./subscriptionEmailContent.js";
+import type { Locale } from "./email.js";
+import type { SubscriptionWinbackCopy } from "./subscriptionEmailContent.js";
+import {
+  accentBox,
+  button,
+  heading,
+  paragraph,
+  type EmailBlock,
+} from "./blocks.js";
+
+export interface SubscriptionWinbackEmailVars {
+  firstName: string | null;
+  /** Consumer-facing brand label injected by the app/composition root. */
+  brandName: string;
+  /** Absolute CTA URL (the customer account / "Wznów" button); null/absent → no button. */
+  ctaUrl?: string | null;
+}
+
+export interface SubscriptionWinbackEmailContent {
+  subject: string;
+  preheader: string;
+  blocks: EmailBlock[];
+}
+
+/** Bind host-selected copy and pure helpers without provider or environment access. */
+export function createSubscriptionWinbackContentFactory(input: {
+  subscriptionEmailContent: Pick<SubscriptionEmailContent, "winback">;
+}) {
+  const { subscriptionEmailContent } = input;
+
+  function subscriptionWinbackEmailContent(
+    locale: Locale,
+    vars: SubscriptionWinbackEmailVars,
+    signoff: string,
+  ): SubscriptionWinbackEmailContent {
+    const copy: SubscriptionWinbackCopy = subscriptionEmailContent.winback[locale];
+    const blocks: EmailBlock[] = [
+      heading(copy.heading),
+      paragraph(copy.greeting(vars.firstName)),
+      paragraph(copy.intro),
+    ];
+    if (copy.reasonsLabel) {
+      blocks.push(paragraph(copy.reasonsLabel(vars.brandName)));
+    }
+    blocks.push(accentBox(copy.reasons));
+
+    if (vars.ctaUrl) {
+      blocks.push(button(copy.cta, vars.ctaUrl));
+    }
+
+    blocks.push(paragraph(copy.outro));
+    blocks.push(paragraph(signoff));
+
+    return {
+      subject: copy.subject,
+      preheader: copy.preheader,
+      blocks,
+    };
+  }
+  return { subscriptionWinbackEmailContent };
+}

package/src/communications/contracts/transactionalDelivery.ts

@@ -0,0 +1,43 @@
+export interface TransactionalDeliveryCommand {
+  readonly idempotencyKey: string;
+  /** Opaque recipient reference; never persisted outside the command fingerprint. */
+  readonly recipientReference: string;
+  /** Opaque template reference; never persisted outside the command fingerprint. */
+  readonly templateReference: string;
+  /** Optional bounded reference to an expiring/revocable access grant. */
+  readonly accessGrantReference?: string;
+}
+
+export type TransactionalDeliveryReceipt = {
+  readonly idempotencyKey: string;
+  readonly commandFingerprint: string;
+  readonly state: "accepted";
+  readonly deliveryReference: string;
+  readonly errorCode: null;
+  readonly attemptCount: number;
+} | {
+  readonly idempotencyKey: string;
+  readonly commandFingerprint: string;
+  readonly state: "failed";
+  readonly deliveryReference: null;
+  readonly errorCode: string;
+  readonly attemptCount: number;
+};
+
+export interface TransactionalDeliveryReceiptStore {
+  readReceipt(idempotencyKey: string): Promise<TransactionalDeliveryReceipt | null>;
+  recordAccepted(input: {
+    idempotencyKey: string;
+    commandFingerprint: string;
+    deliveryReference: string;
+  }): Promise<TransactionalDeliveryReceipt>;
+  recordFailed(input: {
+    idempotencyKey: string;
+    commandFingerprint: string;
+    errorCode: string;
+  }): Promise<TransactionalDeliveryReceipt>;
+}
+
+export interface CapturedTransactionalDeliveryPort {
+  deliver(command: TransactionalDeliveryCommand): Promise<{ deliveryReference: string }>;
+}

package/src/communications/contracts/types.ts

@@ -0,0 +1,58 @@
+type COMMUNICATION_CHANNEL = "email";
+
+type EMAIL_SEND_STATUSES = "queued" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "skipped";
+
+type EMAIL_SEND_SKIP_REASONS = "sequence_paused" | "already_sent" | "template_unavailable" | "race_lost" | "policy_blocked" | "admin_disabled";
+
+
+export type CommunicationChannel = COMMUNICATION_CHANNEL;
+/** The host supplies its persisted provider vocabulary. */
+export type CommunicationProvider<Provider extends string = string> = Provider;
+export type EmailSendStatus = EMAIL_SEND_STATUSES;
+export type EmailSendSkipReason = EMAIL_SEND_SKIP_REASONS;
+
+type COMMUNICATION_PURPOSES = "transactional" | "tester_program" | "marketing_launch_offer" | "marketing_newsletter" | "subscription_dunning" | "admin_notification";
+
+type COMMUNICATION_PERMISSION_STATES = "unknown" | "granted" | "denied" | "suppressed";
+
+type COMMUNICATION_POLICY_DECISIONS = "allowed" | "blocked";
+
+export type CommunicationPurpose = COMMUNICATION_PURPOSES;
+export type CommunicationPermissionState = COMMUNICATION_PERMISSION_STATES;
+export type CommunicationPolicyDecision = COMMUNICATION_POLICY_DECISIONS;
+
+export interface CommunicationRecipientRef {
+  system: "supabase";
+  table: "testers";
+  id: string;
+  email: string | null;
+}
+
+export interface EmailTemplateRef {
+  slug: string;
+  locale: string | null;
+}
+
+export interface EmailSendDedupeKeyInput {
+  recipientId: string;
+  templateSlug: string;
+}
+
+export type EmailSendDecision =
+  | { outcome: "send" }
+  | {
+      outcome: "skip";
+      reason: EmailSendSkipReason;
+      existingMessageId: string | null;
+    };
+
+export interface EmailMessageReadModel<Provider extends string = string> {
+  id: string;
+  channel: CommunicationChannel;
+  recipientId: string;
+  templateSlug: string;
+  status: EmailSendStatus;
+  provider: CommunicationProvider<Provider> | null;
+  providerMessageId: string | null;
+  skippedReason: EmailSendSkipReason | null;
+}

package/src/communications/contribution.ts

@@ -0,0 +1,33 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Host-selected schema inventory: managed and direct installations have different objects. */
+export function createCommunicationsContribution(options: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  routes?: Contribution["routes"];
+  handlers?: Contribution["handlers"];
+  schedules?: Contribution["schedules"];
+  requiredPorts?: readonly string[];
+}): Contribution {
+  const routes = options.routes ?? [];
+  const handlers = options.handlers ?? [];
+  const schedules = options.schedules ?? [];
+  return {
+    manifest: {
+      name: "@openlup/platform", version: options.version, kind: "rail",
+      module: {
+        id: "communications", kind: "capability", provides: ["./communications", "./communications/contracts"],
+        dependsOn: [
+          { module: "data", entries: ["./data"] },
+          { module: "identity", entries: ["./identity"] },
+          { module: "http", entries: ["./http"] },
+        ],
+      },
+      requiredSchema: options.requiredSchema,
+      emits: [], handles: handlers.map((handler) => handler.eventType),
+      schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), routes: routes.map((route) => route.id),
+      requiredPorts: [...new Set(options.requiredPorts ?? [])], env: [],
+    },
+    handlers, schedules, routes,
+  };
+}

package/src/communications/deliveryReconciliation.ts

@@ -0,0 +1,108 @@
+export interface DeliveryPollCandidate {
+  id: string;
+  messageId: string;
+}
+
+export interface DeliveryStatusRead {
+  ok: boolean;
+  httpStatus: number;
+  recipientEmail: string | null;
+}
+
+/** The host maps its protocol to an opaque event type and terminal classification. */
+export interface DeliveryPollObservation {
+  eventType: string;
+  terminal: boolean;
+}
+
+export interface DeliveryReconciliationPort {
+  findFrozenSends(input: { now: string; graceMinutes: number; limit: number }): Promise<DeliveryPollCandidate[]>;
+  applyPolledEvent(input: {
+    sendId: string;
+    messageId: string;
+    eventType: string;
+    eventAt: string;
+    recipientEmail: string | null;
+  }): Promise<void>;
+  recordPollAttempt(input: { sendId: string; attemptedAt: string }): Promise<void>;
+  recordSendNotFound(input: { sendId: string; threshold: number }): Promise<{ abandoned: boolean }>;
+}
+
+export const DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND = 3;
+
+export interface DeliveryReadFailureBreakdown {
+  notFound: number;
+  authFailed: number;
+  network: number;
+  providerError: number;
+  other: number;
+}
+
+export interface DeliveryReconciliationResult {
+  checked: number;
+  reconciled: number;
+  stillPending: number;
+  terminalPolled: number;
+  failures: number;
+  abandoned: number;
+  failureBreakdown: DeliveryReadFailureBreakdown;
+}
+
+function classifyReadFailure(breakdown: DeliveryReadFailureBreakdown, httpStatus: number): void {
+  if (httpStatus === 404) breakdown.notFound += 1;
+  else if (httpStatus === 401 || httpStatus === 403) breakdown.authFailed += 1;
+  else if (httpStatus === 0) breakdown.network += 1;
+  else if (httpStatus >= 500 && httpStatus <= 599) breakdown.providerError += 1;
+  else breakdown.other += 1;
+}
+
+/** Sequential bounded polling around one host-owned atomic convergence writer. */
+export async function runDeliveryReconciliation<Read extends DeliveryStatusRead>(input: {
+  port: DeliveryReconciliationPort;
+  readEmail: (messageId: string) => Promise<Read>;
+  observationFor: (read: Read) => DeliveryPollObservation | null;
+  now: string;
+  graceMinutes: number;
+  limit: number;
+}): Promise<DeliveryReconciliationResult> {
+  const result: DeliveryReconciliationResult = {
+    checked: 0, reconciled: 0, stillPending: 0, terminalPolled: 0, failures: 0, abandoned: 0,
+    failureBreakdown: { notFound: 0, authFailed: 0, network: 0, providerError: 0, other: 0 },
+  };
+  const frozen = await input.port.findFrozenSends({ now: input.now, graceMinutes: input.graceMinutes, limit: input.limit });
+  for (const send of frozen) {
+    result.checked += 1;
+    const read = await input.readEmail(send.messageId);
+    if (read.httpStatus !== 404) {
+      try {
+        await input.port.recordPollAttempt({ sendId: send.id, attemptedAt: input.now });
+      } catch {
+        // Fairness bookkeeping failure must not discard observed delivery truth.
+        result.failures += 1;
+      }
+    }
+    if (!read.ok) {
+      result.failures += 1;
+      classifyReadFailure(result.failureBreakdown, read.httpStatus);
+      if (read.httpStatus === 404) {
+        const { abandoned } = await input.port.recordSendNotFound({ sendId: send.id, threshold: DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND });
+        if (abandoned) result.abandoned += 1;
+      }
+      continue;
+    }
+    const observation = input.observationFor(read);
+    if (!observation) {
+      result.stillPending += 1;
+      continue;
+    }
+    try {
+      await input.port.applyPolledEvent({ sendId: send.id, messageId: send.messageId,
+        eventType: observation.eventType, eventAt: input.now, recipientEmail: read.recipientEmail });
+      result.reconciled += 1;
+      if (observation.terminal) result.terminalPolled += 1;
+    } catch {
+      result.failures += 1;
+    }
+  }
+  return result;
+}

package/src/communications/emailEgress.ts

@@ -0,0 +1,111 @@
+import type { AuthEmailTransportPort, AuthEmailTransportResult } from "./contracts/authEmail.js";
+import type { EmailMessage, EmailSendResult, EmailTransport } from "./emailTransport.js";
+
+export interface EmailEgressContext {
+  mode: "production" | "sandbox_direct" | "sandbox_sink";
+  reason: string;
+  intendedRecipient: string;
+  recipient: string;
+  /** Selected by the host; consumed only by its concrete sender, never logged. */
+  credential: string;
+  environmentTag: "production" | "non_production";
+}
+
+export type EmailEgressDecision = EmailEgressContext | { mode: "drop"; reason: string } | { mode: "blocked"; reason: string };
+export type EmailEgressPolicy = (intendedRecipient: string) => EmailEgressDecision | Promise<EmailEgressDecision>;
+
+const admitted = new WeakSet<EmailTransport>();
+const admittedAuth = new WeakSet<AuthEmailTransportPort>();
+
+/**
+ * Host composition bridge for an implementation that already enforces egress
+ * internally. This is a trust boundary: its sender must itself refuse unknown
+ * policy before effects. New network adapters should use createGuardedEmailTransport.
+ * Neither a provider name nor an object property establishes admission.
+ */
+export function admitPolicyEnforcedEmailTransport<T extends EmailTransport>(transport: T): T {
+  admitted.add(transport);
+  return transport;
+}
+
+/** Mandatory boundary for supported injected transports; raw objects fail closed. */
+export function guardEmailTransport(transport: EmailTransport): EmailTransport {
+  if (admitted.has(transport)) return transport;
+  return { providerKind: transport.providerKind, send: async () => refused("email_egress_unadmitted") };
+}
+
+/** Construct a network adapter whose sender sees only a validated host decision. */
+export function createGuardedEmailTransport(input: {
+  providerKind: string;
+  policy: EmailEgressPolicy;
+  send: (message: EmailMessage, context: Readonly<EmailEgressContext>) => Promise<EmailSendResult>;
+}): EmailTransport {
+  return admitPolicyEnforcedEmailTransport({
+    providerKind: input.providerKind,
+    async send(message) {
+      let decision: unknown;
+      try { decision = await input.policy(message.to); }
+      catch { return refused("email_egress_policy_unavailable"); }
+      if (!validDecision(decision, message.to)) return refused("email_egress_policy_invalid");
+      if (decision.mode === "blocked") return refused("email_egress_blocked", decision.reason);
+      if (decision.mode === "drop") return {
+        outcome: { ok: true, resendId: null, httpStatus: 0, providerError: null, aborted: false,
+          suppressed: "drop", egressMode: "drop", egressReason: decision.reason },
+        providerResponse: { suppressed: "drop", egress_reason: decision.reason },
+      };
+      const context = Object.freeze({ ...decision });
+      const result = await input.send({ ...message, to: context.recipient }, context);
+      return { ...result, outcome: { ...result.outcome, egressMode: context.mode, egressReason: context.reason } };
+    },
+  });
+}
+
+function validDecision(value: unknown, intended: string): value is EmailEgressDecision {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const d = value as Record<string, unknown>;
+  // Policy diagnostics are bounded codes, never arbitrary exception/secret text.
+  if (typeof d.reason !== "string" || !/^[a-z][a-z0-9_]{0,79}$/.test(d.reason)) return false;
+  if (d.mode === "drop" || d.mode === "blocked") return Object.keys(d).every((key) => key === "mode" || key === "reason");
+  if (d.mode !== "production" && d.mode !== "sandbox_direct" && d.mode !== "sandbox_sink") return false;
+  if (!Object.keys(d).every((key) => ["mode", "reason", "intendedRecipient", "recipient", "credential", "environmentTag"].includes(key))) return false;
+  if (!mailbox(intended) || d.intendedRecipient !== intended || !mailbox(d.recipient)) return false;
+  if (d.mode !== "sandbox_sink" && d.recipient !== intended) return false;
+  if (typeof d.credential !== "string" || !d.credential.trim()) return false;
+  return d.environmentTag === (d.mode === "production" ? "production" : "non_production");
+}
+
+function mailbox(value: unknown): value is string {
+  return typeof value === "string" && /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/.test(value);
+}
+
+function refused(code: string, reason?: string): EmailSendResult {
+  return { outcome: { ok: false, resendId: null, httpStatus: 0, providerError: code, aborted: false,
+    ...(reason ? { egressReason: reason } : {}) }, providerResponse: { egress_reason: code } };
+}
+
+/** Preserve the Auth envelope/result mapping while retaining package admission. */
+export function createAuthEmailTransport(transport: EmailTransport): AuthEmailTransportPort {
+  const guarded = guardEmailTransport(transport);
+  const auth: AuthEmailTransportPort = {
+    providerKind: transport.providerKind,
+    async send(message) {
+      const result = await guarded.send({ from: message.sender, to: message.recipient,
+        subject: message.subject, html: message.html, text: message.text });
+      return { outcome: { ...result.outcome, messageId: result.outcome.resendId }, providerResponse: result.providerResponse };
+    },
+  };
+  admittedAuth.add(auth);
+  return auth;
+}
+
+/** Raw Auth closures must compose through the admitted email transport bridge. */
+export function guardAuthEmailTransport(transport: AuthEmailTransportPort): AuthEmailTransportPort {
+  if (admittedAuth.has(transport)) return transport;
+  return {
+    providerKind: transport.providerKind,
+    async send(): Promise<AuthEmailTransportResult> {
+      const result = refused("email_egress_unadmitted");
+      return { outcome: { ...result.outcome, messageId: null }, providerResponse: result.providerResponse };
+    },
+  };
+}