@jini-ai/platform 0.5.8 → 0.5.10

package/dist/mail/policy.js

@@ -0,0 +1,155 @@
+/**
+ * @file Delivery policy in front of any mail provider: one place that refuses, dedups, rate-limits,
+ * and records outcomes, so no provider adapter has to re-implement (or forget) these rules.
+ *
+ * Order per recipient: attachments → bulk unsubscribe headers → suppression → test mode → rate
+ * limit → ledger reserve → send → ledger mark. Refusals before the reserve leave no ledger row, so a
+ * corrected retry under the same idempotency key is not mistaken for a duplicate.
+ */
+import { createHash } from "node:crypto";
+/**
+ * The one throttling code of the mail contract: the local token bucket's refusal and a provider's own
+ * throttling (e.g. an HTTP 429, which adapters normalize to it) are the same retryable back-pressure,
+ * with `retryAfterMs` as the hint. Callers defer such a recipient instead of recording a failure.
+ */
+export const MAIL_RATE_LIMITED = "MAIL_RATE_LIMITED";
+/** Whether a send result is the typed rate-limited refusal. @complexity O(1). */
+export function isMailRateLimited({ result }) {
+    return !result.ok && result.errorCode === MAIL_RATE_LIMITED;
+}
+/** Bulk lane only for `purpose: "bulk"`; everything else (incl. `feature:*`) is transactional. */
+export function laneForPurpose({ purpose }) {
+    return purpose === "bulk" ? "bulk" : "transactional";
+}
+/** RFC 8058 one-click needs both headers; header names are case-insensitive. */
+export function hasOneClickUnsubscribe({ headers }) {
+    const names = new Set(Object.keys(headers ?? {}).map((name) => name.toLowerCase()));
+    return names.has("list-unsubscribe") && names.has("list-unsubscribe-post");
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function canonicalAddress(address) {
+    return address === undefined ? null : [address.email, address.name ?? null];
+}
+/**
+ * Stable per-recipient payload hash: a reused key with different content is a caller bug. It covers
+ * everything the provider delivers (addresses with display names, reply-to, subject, bodies, headers,
+ * attachment names, types and bytes), so a changed message under a sent key is a conflict rather than
+ * the earlier message's success. Attachment bytes enter as their own sha256 to keep the input small.
+ * @complexity O(message size).
+ */
+export function mailPayloadHash({ message }) {
+    const { subject, html, text, headers, from, to, replyTo, attachments } = message;
+    const files = (attachments ?? []).map((a) => [a.filename, a.contentType, sha256(a.contentBase64)]);
+    return sha256(JSON.stringify([canonicalAddress(from), canonicalAddress(to), canonicalAddress(replyTo), subject, html ?? null, text ?? null, Object.entries(headers ?? {}).sort(), files]));
+}
+function refuse(errorCode, message, extra = {}) {
+    return { ok: false, retryable: extra.retryable ?? false, errorCode, message, ...(extra.retryAfterMs === undefined ? {} : { retryAfterMs: extra.retryAfterMs }), ...(extra.unknown ? { unknown: true } : {}) };
+}
+/** Pre-dispatch refusals that never touch the ledger. @complexity O(headers). */
+async function preflight(required) {
+    const { message, options, lane, deps } = required;
+    if ((message.attachments?.length ?? 0) > 0 && !deps.supportsAttachments) {
+        return refuse("MAIL_ATTACHMENTS_UNSUPPORTED", `provider ${deps.providerId} cannot send attachments`);
+    }
+    if (lane === "bulk" && !hasOneClickUnsubscribe({ headers: message.headers })) {
+        return refuse("MAIL_BULK_UNSUBSCRIBE_REQUIRED", "bulk mail needs List-Unsubscribe and List-Unsubscribe-Post (RFC 8058) headers");
+    }
+    const normalizedAddress = message.to.email.trim().toLowerCase();
+    if (await deps.suppression.isSuppressed({ workspaceId: options.workspaceId, normalizedAddress, lane })) {
+        return refuse("MAIL_RECIPIENT_SUPPRESSED", `recipient is suppressed for ${lane} mail`);
+    }
+    return null;
+}
+/**
+ * Maps an existing ledger row to the result a duplicate delivery returns. A resendable `unknown` row
+ * never gets here: the ledger reclaims it atomically in `reserve` (`reclaimUnknown`), so only the
+ * one caller that won that claim re-sends.
+ */
+function existingResult(required) {
+    const { existing, payloadHash } = required;
+    if (existing.payloadHash !== payloadHash)
+        return refuse("MAIL_IDEMPOTENCY_CONFLICT", "idempotency key reused with a different message");
+    if (existing.outcome === "sent")
+        return { ok: true, providerMessageId: existing.providerMessageId ?? "", acceptedAt: required.nowIso() };
+    // `reserved` = another worker is sending now, or a crash mid-send: the outcome is unknown.
+    return refuse("MAIL_OUTCOME_UNKNOWN", "an earlier attempt with this key has an unknown outcome", { unknown: true });
+}
+/** Provider call → ledger outcome; a throw is unknown (the provider may have accepted it). */
+async function dispatch(required) {
+    try {
+        return await required.send({ message: required.message });
+    }
+    catch (err) {
+        return refuse("MAIL_OUTCOME_UNKNOWN", err instanceof Error ? err.message : String(err), { unknown: true });
+    }
+}
+function outcomeOf(result) {
+    if (result.ok)
+        return "sent";
+    return result.unknown ? "unknown" : "failed";
+}
+/** Test mode: redirect rewrites the recipient; capture stores the message and sends nothing. */
+async function applyTestMode(required, optional = {}) {
+    const { message, options, lane } = required;
+    const mode = optional.testMode;
+    if (mode === undefined)
+        return { message };
+    if (mode.kind === "redirect") {
+        return { message: { ...message, to: mode.to, headers: { ...message.headers, "X-Original-To": message.to.email } } };
+    }
+    const { id } = await mode.sink.capture({ message, lane, idempotencyKey: options.idempotencyKey });
+    return { result: { ok: true, providerMessageId: `captured:${id}`, acceptedAt: required.nowIso() } };
+}
+/**
+ * Builds the policy. @complexity O(1) ledger round-trips per recipient.
+ * @example createMailDeliveryPolicy({ providerId: "smtp", ledger, suppression, supportsAttachments: true })
+ */
+export function createMailDeliveryPolicy(required, optional = {}) {
+    const resendPolicy = optional.resendPolicy ?? (() => "on_unknown");
+    const nowIso = optional.nowIso ?? (() => new Date().toISOString());
+    return {
+        async deliver({ message, options, send }) {
+            const lane = laneForPurpose({ purpose: options.purpose });
+            const refused = await preflight({ message, options, lane, deps: required });
+            if (refused)
+                return refused;
+            const tested = await applyTestMode({ message, options, lane, nowIso }, optional.testMode ? { testMode: optional.testMode } : {});
+            if ("result" in tested)
+                return tested.result;
+            const taken = optional.limiter?.tryTake({ lane }) ?? { ok: true };
+            if (!taken.ok)
+                return refuse(MAIL_RATE_LIMITED, `${lane} lane is rate limited`, { retryable: true, retryAfterMs: taken.retryAfterMs });
+            const key = { workspaceId: options.workspaceId, idempotencyKey: options.idempotencyKey, recipient: message.to.email.trim().toLowerCase() };
+            const payloadHash = mailPayloadHash({ message });
+            const reclaimUnknown = resendPolicy({ purpose: options.purpose }) === "on_unknown";
+            const reserved = await required.ledger.reserve({ ...key, payloadHash, lane, providerId: required.providerId }, { reclaimUnknown });
+            if (reserved.status === "existing")
+                return existingResult({ existing: reserved, payloadHash, nowIso });
+            const result = await dispatch({ message: tested.message, send });
+            await required.ledger.mark({ ...key, outcome: outcomeOf(result), ...(result.ok ? { providerMessageId: result.providerMessageId } : { errorCode: result.errorCode }) });
+            return result;
+        },
+    };
+}
+/** Jini-shaped `MailerPort` decorator over the policy; batches go recipient by recipient. */
+export function createPolicyMailer(required) {
+    const { inner, policy } = required;
+    const sendOne = (input, optional) => {
+        const { message, ...delivery } = input;
+        return policy.deliver({ message, options: { ...delivery, ...optional }, send: (call) => inner.send({ ...delivery, message: call.message }, optional) });
+    };
+    return {
+        capabilities: (empty) => inner.capabilities(empty),
+        send: (input, optional = {}) => sendOne(input, optional),
+        async sendBatch({ messages, ...delivery }, optional = {}) {
+            // Per-recipient ledger rows need per-recipient dispatch; a provider batch would share one outcome.
+            const results = [];
+            for (const message of messages)
+                results.push(await sendOne({ ...delivery, message }, optional));
+            return results;
+        },
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/mail/ports.d.ts

@@ -1,5 +1,5 @@
 import type { UUID } from "@jini-ai/core/primitives";
-import type { MailerCapabilities, MailerSendResult, MailerSendRequired, MailerBatchRequired, MailerOptional } from "./types.js";
+import type { MailerCapabilities, MailerSendResult, OutboundEmail, MailerSendRequired, MailerBatchRequired, MailerOptional } from "./types.js";
 export type { MailerCapabilities, MailerSendOptions, MailerSendResult, OutboundEmail } from "./types.js";
 export interface MailerPort {
     capabilities(_required: Record<string, never>): MailerCapabilities;
@@ -8,23 +8,62 @@ export interface MailerPort {
 }
 export type ConsoleMailerAdapter = MailerPort;
 export type InMemoryMailerAdapter = MailerPort;
+/** `all` blocks every send (hard bounce, manual); `bulk` blocks only bulk mail (complaints), so a
+ * member who marked a newsletter as spam can still receive their own sign-in link. */
+export type MailSuppressionScope = "all" | "bulk";
 export interface MailSuppressionRepoPort {
     isSuppressed(required: {
         workspaceId: UUID;
         normalizedAddress: string;
-        scope: "global" | {
-            module: string;
-        };
+        /** The lane being sent: `transactional` consults `all` only, `bulk` consults both scopes. */
+        lane: MailDeliveryLane;
     }): Promise<boolean>;
     suppress(required: {
         workspaceId: UUID;
         normalizedAddress: string;
-        scope: "global" | {
-            module: string;
-        };
+        scope: MailSuppressionScope;
         reason: "bounced" | "complained" | "manual";
     }): Promise<void>;
 }
+/** Hard delivery lanes. Distinct from `MailerSendOptions.lane` (interactive/notification readiness). */
+export type MailDeliveryLane = "transactional" | "bulk";
+export type MailLedgerOutcome = "reserved" | "sent" | "failed" | "unknown";
+export interface MailSendLedgerPort {
+    /**
+     * Atomically insert (workspaceId, idempotencyKey, recipient) as `reserved`. An existing row is
+     * returned as-is, except `failed`, which the port flips back to `reserved` in the same statement
+     * (a definitive failure means nothing was sent, so retrying under the same identity is safe).
+     * With `optional.reclaimUnknown`, an `unknown` row with the SAME payloadHash is flipped to
+     * `reserved` in that same statement too: the caller that wins the flip is the only one that
+     * re-sends, and a concurrent retry sees `reserved` (an unknown outcome) instead of also re-sending.
+     */
+    reserve(required: {
+        workspaceId: UUID;
+        idempotencyKey: string;
+        recipient: string;
+        payloadHash: string;
+        lane: MailDeliveryLane;
+        providerId: string;
+    }, optional?: {
+        reclaimUnknown?: boolean;
+    }): Promise<{
+        status: "reserved";
+    } | {
+        status: "existing";
+        outcome: Exclude<MailLedgerOutcome, "failed">;
+        payloadHash: string;
+        providerMessageId?: string;
+    }>;
+    mark(required: {
+        workspaceId: UUID;
+        idempotencyKey: string;
+        recipient: string;
+        outcome: Exclude<MailLedgerOutcome, "reserved">;
+        providerMessageId?: string;
+        errorCode?: string;
+    }): Promise<void>;
+}
+/** @deprecated Racy check-then-send pair; use {@link MailSendLedgerPort}. Kept for type consumers. */
 export interface MailSendDedupRepoPort {
     wasSent(required: {
         workspaceId: UUID;
@@ -35,6 +74,16 @@ export interface MailSendDedupRepoPort {
         idempotencyKey: string;
     }): Promise<void>;
 }
+/** Test/capture mode sink: messages are stored for the operator instead of leaving the process. */
+export interface MailCapturePort {
+    capture(required: {
+        message: OutboundEmail;
+        lane: MailDeliveryLane;
+        idempotencyKey: string;
+    }): Promise<{
+        id: string;
+    }>;
+}
 export interface DeliveryReadinessPolicy {
     isReady(required: {
         capabilityName: string;

package/dist/mail/provider.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @file Mail provider contract + keyed registry (email provider contract v1, 2026-10-21).
+ *
+ * A provider is a {@link MailAdapterModule} that also names itself, declares the credential fields
+ * it needs and its capabilities, and optionally parses delivery feedback and reports what a sending
+ * domain must publish (SPF/DKIM/DMARC). Selection is explicit: the host stores
+ * `mail.provider.{transactional,bulk}` and never picks "the first provider with a credential".
+ */
+import { type DomainRequirement, type ProviderContext, type ProviderRegistry, type ProviderResult } from "@jini-ai/core/provider-registry";
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { MailAdapterCredential, MailAdapterModule } from "./adapter-module.js";
+import type { MailDeliveryLane } from "./ports.js";
+import type { MailerFeedbackEvent } from "./types.js";
+/** Provider token bucket: sustained rate plus burst. Absent = no provider-declared limit. */
+export interface MailRateLimit {
+    readonly perSecond: number;
+    readonly burst: number;
+}
+export interface MailProviderCapabilities {
+    /** False for local drivers (console): they never count as real delivery. */
+    readonly hosted: boolean;
+    /** True exactly when the module ships a {@link MailFeedbackParser}. */
+    readonly feedback: boolean;
+    /** True exactly when the module implements domainRequirements + domainStatus. */
+    readonly domainVerification: boolean;
+    readonly rateLimit?: MailRateLimit;
+}
+export interface MailFeedbackParser {
+    /** Raw bytes in; never throws. Any of `secrets` may match so a webhook secret can rotate. */
+    verify(required: {
+        rawBody: Uint8Array;
+        headers: Readonly<Record<string, string>>;
+        secrets: readonly string[];
+        now: number;
+    }): boolean;
+    /** Headers are passed so a parser can key events on a delivery id (e.g. `svix-id`).
+     * Each event must carry eventId + recipient, or the ingest drops it (no dedup key, no suppression key). */
+    parse(required: {
+        rawBody: Uint8Array;
+        workspaceId: string;
+        headers: Readonly<Record<string, string>>;
+    }): readonly MailerFeedbackEvent[] | {
+        error: string;
+    };
+}
+/** Per-call context: who the call acts for plus the host-resolved credential and guarded HTTP. */
+export interface MailProviderCallContext extends ProviderContext {
+    readonly credential: MailAdapterCredential;
+    readonly httpClient: HttpClientPort;
+}
+export type MailDomainState = "verified" | "pending" | "failed" | "not_found";
+export interface MailProviderModule extends MailAdapterModule {
+    readonly id: string;
+    readonly label: string;
+    /** Credential fields the host must resolve (e.g. `token`, `username`, `baseUrl`). */
+    readonly credentialKeys: readonly string[];
+    /** Separate vault key for the webhook signing secret, so it rotates independently of the API key. */
+    readonly webhookSecretKey?: string;
+    readonly capabilities: MailProviderCapabilities;
+    readonly feedback?: MailFeedbackParser;
+    /** DNS records the provider needs before it will send as `domain`; satisfied through the DNS port. */
+    domainRequirements?(ctx: MailProviderCallContext, required: {
+        domain: string;
+    }): Promise<ProviderResult<DomainRequirement>>;
+    domainStatus?(ctx: MailProviderCallContext, required: {
+        domain: string;
+    }): Promise<ProviderResult<{
+        domain: string;
+        state: MailDomainState;
+    }>>;
+}
+/** Shape check run by the registry for core and plugin registrations. @complexity O(k) keys. */
+export declare function validateMailProvider({ provider }: {
+    provider: MailProviderModule;
+}): string | undefined;
+export type MailProviderRegistry = ProviderRegistry<MailProviderModule>;
+/** Mail registry over the shared keyed registry; built-ins throw on a bad registration, plugins are refused. */
+export declare function createMailProviderRegistry(_required?: Record<string, never>, optional?: {
+    builtins?: readonly MailProviderModule[];
+}): MailProviderRegistry;
+export declare const MAIL_PROVIDER_SETTING_KEY = "mail.provider";
+/** One provider per lane; equal ids today, separable later without a data migration. null = unconfigured. */
+export interface MailProviderSetting {
+    readonly transactional: string | null;
+    readonly bulk: string | null;
+}
+/**
+ * The value written on first boot: whatever the host was effectively using, so a live site never
+ * silently switches provider when selection becomes explicit. A local driver (console) or nothing
+ * becomes `null` — the explicit `unconfigured` state, not a fake "working" default.
+ */
+export declare function initialMailProviderSetting(_required: Record<string, never>, optional?: {
+    effectiveProviderId?: string | null;
+    registry?: MailProviderRegistry;
+}): MailProviderSetting;
+export type MailLaneState = "ready" | "unconfigured" | "unknown_provider" | "missing_credential" | "local_only";
+export interface MailLaneStatus {
+    readonly lane: MailDeliveryLane;
+    readonly providerId: string | null;
+    readonly state: MailLaneState;
+}
+export type MailStatusWarning = "sender_unverified" | "sender_unknown";
+export interface MailStatus {
+    /** `unconfigured` drives the blocking admin banner; owner sign-in must never depend on mail. */
+    readonly state: "ready" | "unconfigured" | "degraded";
+    readonly lanes: readonly MailLaneStatus[];
+    readonly warnings: readonly MailStatusWarning[];
+}
+/** Pure status projection for `mail_status` and the admin banner. @complexity O(lanes). */
+export declare function computeMailStatus(required: {
+    setting: MailProviderSetting;
+    registry: MailProviderRegistry;
+    hasCredential: (id: string) => boolean;
+}, optional?: {
+    senderDomainState?: MailDomainState | null;
+}): MailStatus;
+//# sourceMappingURL=provider.d.ts.map

package/dist/mail/provider.js

@@ -0,0 +1,74 @@
+/**
+ * @file Mail provider contract + keyed registry (email provider contract v1, 2026-10-21).
+ *
+ * A provider is a {@link MailAdapterModule} that also names itself, declares the credential fields
+ * it needs and its capabilities, and optionally parses delivery feedback and reports what a sending
+ * domain must publish (SPF/DKIM/DMARC). Selection is explicit: the host stores
+ * `mail.provider.{transactional,bulk}` and never picks "the first provider with a credential".
+ */
+import { createProviderRegistry, } from "@jini-ai/core/provider-registry";
+/** Shape check run by the registry for core and plugin registrations. @complexity O(k) keys. */
+export function validateMailProvider({ provider }) {
+    if (typeof provider !== "object" || provider === null)
+        return "not an object";
+    if (typeof provider.create !== "function")
+        return "create() is missing";
+    if (!Array.isArray(provider.credentialKeys) || !provider.credentialKeys.every((key) => typeof key === "string"))
+        return "credentialKeys must be a string array";
+    const caps = provider.capabilities;
+    if (typeof caps !== "object" || caps === null)
+        return "capabilities are missing";
+    // A capability claim without the code behind it is how Resend once advertised feedback with no route.
+    if (caps.feedback !== (provider.feedback !== undefined))
+        return "capabilities.feedback must match the presence of a feedback parser";
+    const hasDomain = typeof provider.domainRequirements === "function" && typeof provider.domainStatus === "function";
+    if (caps.domainVerification !== hasDomain)
+        return "capabilities.domainVerification must match domainRequirements + domainStatus";
+    return undefined;
+}
+/** Mail registry over the shared keyed registry; built-ins throw on a bad registration, plugins are refused. */
+export function createMailProviderRegistry(_required = {}, optional = {}) {
+    const seed = (optional.builtins ?? []).map((provider) => ({ id: provider.id, provider, label: provider.label }));
+    return createProviderRegistry({ contract: "mail" }, { validate: validateMailProvider, seed });
+}
+// ---------------------------------------------------------------------------------------------
+// Selection setting + status.
+// ---------------------------------------------------------------------------------------------
+export const MAIL_PROVIDER_SETTING_KEY = "mail.provider";
+/**
+ * The value written on first boot: whatever the host was effectively using, so a live site never
+ * silently switches provider when selection becomes explicit. A local driver (console) or nothing
+ * becomes `null` — the explicit `unconfigured` state, not a fake "working" default.
+ */
+export function initialMailProviderSetting(_required, optional = {}) {
+    const id = optional.effectiveProviderId ?? null;
+    const hosted = id !== null && optional.registry?.get({ id })?.provider.capabilities.hosted === true;
+    const value = hosted ? id : null;
+    return { transactional: value, bulk: value };
+}
+function laneStatus(required) {
+    const { lane, providerId, registry } = required;
+    if (providerId === null)
+        return { lane, providerId, state: "unconfigured" };
+    const entry = registry.get({ id: providerId });
+    if (!entry)
+        return { lane, providerId, state: "unknown_provider" };
+    if (!entry.provider.capabilities.hosted)
+        return { lane, providerId, state: "local_only" };
+    return { lane, providerId, state: required.hasCredential(providerId) ? "ready" : "missing_credential" };
+}
+/** Pure status projection for `mail_status` and the admin banner. @complexity O(lanes). */
+export function computeMailStatus(required, optional = {}) {
+    const { setting, registry, hasCredential } = required;
+    const lanes = ["transactional", "bulk"].map((lane) => laneStatus({ lane, providerId: setting[lane], registry, hasCredential }));
+    const warnings = [];
+    const domain = optional.senderDomainState;
+    if (domain === null)
+        warnings.push("sender_unknown");
+    else if (domain !== undefined && domain !== "verified")
+        warnings.push("sender_unverified");
+    const ready = lanes.filter((status) => status.state === "ready").length;
+    const state = ready === lanes.length ? "ready" : lanes[0].state === "unconfigured" ? "unconfigured" : "degraded";
+    return { state, lanes, warnings };
+}
+//# sourceMappingURL=provider.js.map

package/dist/mail/rate-limit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Per-provider token bucket with capacity reserved for transactional mail.
+ *
+ * Bulk and transactional share one provider quota, so a newsletter run could otherwise starve a
+ * sign-in link for minutes. Bulk may only take tokens above `reservedForTransactional`; transactional
+ * may drain the bucket to zero.
+ */
+import type { MailRateLimit } from "./provider.js";
+import type { MailDeliveryLane } from "./ports.js";
+export interface MailLaneLimiter {
+    tryTake(required: {
+        lane: MailDeliveryLane;
+    }): {
+        ok: true;
+    } | {
+        ok: false;
+        retryAfterMs: number;
+    };
+}
+/**
+ * @param required.limit - Sustained rate and burst size (the bucket starts full).
+ * @param optional.reservedForTransactional - Tokens bulk may never consume; defaults to 20% of burst,
+ *   at least 1 (never the whole burst).
+ * @param optional.now - Injected clock in ms.
+ * @complexity O(1) per take.
+ */
+export declare function createMailLaneLimiter(required: {
+    limit: MailRateLimit;
+}, optional?: {
+    reservedForTransactional?: number;
+    now?: () => number;
+}): MailLaneLimiter;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/mail/rate-limit.js

@@ -0,0 +1,35 @@
+/**
+ * @param required.limit - Sustained rate and burst size (the bucket starts full).
+ * @param optional.reservedForTransactional - Tokens bulk may never consume; defaults to 20% of burst,
+ *   at least 1 (never the whole burst).
+ * @param optional.now - Injected clock in ms.
+ * @complexity O(1) per take.
+ */
+export function createMailLaneLimiter(required, optional = {}) {
+    const { perSecond, burst } = required.limit;
+    if (!(perSecond > 0) || !(burst >= 1))
+        throw new RangeError("mail rate limit needs perSecond > 0 and burst >= 1");
+    const now = optional.now ?? Date.now;
+    // At least one token whenever burst > 1: 20% of a small burst (Resend's 2) floors to 0, which let
+    // bulk drain the bucket and starve an interactive sign-in link. Never all of it (bulk must move).
+    const reserved = Math.min(optional.reservedForTransactional ?? Math.max(1, Math.floor(burst * 0.2)), burst - 1);
+    let tokens = burst;
+    let last = now();
+    const refill = () => {
+        const at = now();
+        tokens = Math.min(burst, tokens + ((at - last) / 1000) * perSecond);
+        last = at;
+    };
+    return {
+        tryTake({ lane }) {
+            refill();
+            const floor = lane === "bulk" ? reserved : 0;
+            if (tokens - 1 >= floor) {
+                tokens -= 1;
+                return { ok: true };
+            }
+            return { ok: false, retryAfterMs: Math.ceil(((floor + 1 - tokens) / perSecond) * 1000) };
+        },
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/mail/sender-identity.d.ts

@@ -0,0 +1,68 @@
+import type { EmailAddress } from "./types.js";
+/**
+ * @file The one place a system email's `From` is decided. Each caller passes its own `*.local`
+ * placeholder as the fallback; the placeholder is only ever used by a mailer that sends nothing,
+ * because real providers (hosted APIs, SMTP relays) reject a `.local` sender outright.
+ *
+ * Order: the site's configured sender wins whatever the mailer is. With no configured sender, a
+ * non-delivering mailer (Console, in-memory) keeps the placeholder, so local development still
+ * works with zero setup. A delivering mailer with no configured sender throws
+ * {@link SenderIdentityNotConfiguredError} instead of handing the provider a From it will refuse.
+ * Hosts supply the settings read, the boot-time settle and the operator-facing error copy.
+ */
+/** Drivers that never hand a message to a real provider, so a `.local` From cannot be rejected.
+ *  `console` prints to stdout; `memory` is the in-process fake. Every other driver is treated as
+ *  delivering: an unknown driver fails closed. */
+export declare const NON_DELIVERING_MAIL_DRIVERS: ReadonlySet<string>;
+/** Thrown when a delivering mailer is active but the site has no sender address configured. */
+export declare class SenderIdentityNotConfiguredError extends Error {
+    readonly code = "mail_sender_not_configured";
+    /** @param optional.message host copy naming where the sender is configured. */
+    constructor(required: {
+        workspaceId: string;
+        driver: string;
+    }, optional?: {
+        message?: string;
+    });
+}
+/** The site's saved sender, either part possibly absent. */
+export interface ConfiguredMailSender {
+    email?: string;
+    name?: string;
+}
+/** Resolves the `From` for one system email. */
+export interface MailSenderIdentityPort {
+    /**
+     * @param required.fallback The caller's placeholder sender; its `name` also fills in a missing
+     *   configured display name.
+     * @throws SenderIdentityNotConfiguredError See this file's header.
+     */
+    resolve(required: {
+        workspaceId: string;
+        fallback: EmailAddress;
+    }, optional?: Record<string, never>): Promise<EmailAddress>;
+}
+export interface CreateMailSenderIdentityResolverOptional {
+    /** Reads the site's saved sender. Absent: nothing is configured (hermetic test roots). */
+    readConfiguredSender?: (required: {
+        workspaceId: string;
+    }) => Promise<ConfiguredMailSender | null>;
+    /** Waits for the host's boot-time mailer swap. Without it, a read in the first moments after boot,
+     *  or right after a key is saved, can still see the Console fallback and pick the placeholder for
+     *  a send that then reaches the real provider. */
+    settle?: () => Promise<void>;
+    /** Builds the refusal; default {@link SenderIdentityNotConfiguredError} with neutral copy. */
+    notConfigured?: (required: {
+        workspaceId: string;
+        driver: string;
+    }) => Error;
+}
+/**
+ * Builds the resolver over the active mailer's driver. See this file's header for the decision order.
+ * @param required.readDriver the active mailer's driver, read after `settle`.
+ * @complexity One settle, at most one settings read, one driver read.
+ */
+export declare function createMailSenderIdentityResolver(required: {
+    readDriver: () => string;
+}, optional?: CreateMailSenderIdentityResolverOptional): MailSenderIdentityPort;
+//# sourceMappingURL=sender-identity.d.ts.map

package/dist/mail/sender-identity.js

@@ -0,0 +1,50 @@
+/**
+ * @file The one place a system email's `From` is decided. Each caller passes its own `*.local`
+ * placeholder as the fallback; the placeholder is only ever used by a mailer that sends nothing,
+ * because real providers (hosted APIs, SMTP relays) reject a `.local` sender outright.
+ *
+ * Order: the site's configured sender wins whatever the mailer is. With no configured sender, a
+ * non-delivering mailer (Console, in-memory) keeps the placeholder, so local development still
+ * works with zero setup. A delivering mailer with no configured sender throws
+ * {@link SenderIdentityNotConfiguredError} instead of handing the provider a From it will refuse.
+ * Hosts supply the settings read, the boot-time settle and the operator-facing error copy.
+ */
+/** Drivers that never hand a message to a real provider, so a `.local` From cannot be rejected.
+ *  `console` prints to stdout; `memory` is the in-process fake. Every other driver is treated as
+ *  delivering: an unknown driver fails closed. */
+export const NON_DELIVERING_MAIL_DRIVERS = new Set(["console", "memory"]);
+/** Thrown when a delivering mailer is active but the site has no sender address configured. */
+export class SenderIdentityNotConfiguredError extends Error {
+    code = "mail_sender_not_configured";
+    /** @param optional.message host copy naming where the sender is configured. */
+    constructor(required, optional = {}) {
+        super(optional.message ?? `No sender address is configured for workspace ${required.workspaceId}, so the "${required.driver}" mailer ` +
+            `cannot send: real mail providers reject the placeholder no-reply@*.local sender. Configure a sender address the provider accepts.`);
+        this.name = "SenderIdentityNotConfiguredError";
+    }
+}
+/** An address with its display name only when there is one (exact optional `name`). */
+function withName(email, name) {
+    return name === undefined ? { email } : { email, name };
+}
+/**
+ * Builds the resolver over the active mailer's driver. See this file's header for the decision order.
+ * @param required.readDriver the active mailer's driver, read after `settle`.
+ * @complexity One settle, at most one settings read, one driver read.
+ */
+export function createMailSenderIdentityResolver(required, optional = {}) {
+    const { notConfigured = (details) => new SenderIdentityNotConfiguredError(details) } = optional;
+    return {
+        resolve: async ({ workspaceId, fallback }) => {
+            const configured = await optional.readConfiguredSender?.({ workspaceId });
+            if (configured?.email)
+                return withName(configured.email, configured.name ?? fallback.name);
+            await optional.settle?.();
+            const driver = required.readDriver();
+            if (NON_DELIVERING_MAIL_DRIVERS.has(driver))
+                return fallback;
+            throw notConfigured({ workspaceId, driver });
+        },
+    };
+}
+//# sourceMappingURL=sender-identity.js.map

package/dist/mail/types.d.ts

@@ -50,6 +50,11 @@ export type MailerSendResult = {
     retryable: boolean;
     errorCode: string;
     message: string;
+    /** The provider may have accepted the message (timeout after submit, crash mid-send): never
+     * auto-retry under a new identity; the send ledger records the outcome as `unknown`. */
+    unknown?: boolean;
+    /** Rate-limit hint (provider 429 or the local token bucket); absent means "caller's backoff". */
+    retryAfterMs?: number;
 };
 export interface MailerCapabilities {
     driver: string;
@@ -68,6 +73,10 @@ export interface MailerFeedbackEvent {
         ref?: string;
     };
     kind: "delivered" | "bounced" | "complained";
+    /** Provider event id: the inbox dedups replays on (providerId, eventId). Optional for v1 parsers. */
+    eventId?: string;
+    /** Lower-cased recipient address; suppression needs it, provider message ids alone cannot key it. */
+    recipient?: string;
     hardBounce: boolean;
     occurredAt: ISODateTime;
 }