@jini-ai/platform 0.6.11 → 0.6.15-rc.1

package/dist/mail/engine-contracts.d.ts

@@ -0,0 +1,129 @@
+import type { MailAdapterCredential } from "./adapter-module.js";
+import type { MailDomainState, MailProviderCapabilities, MailProviderRegistry, MailProviderSetting, MailStatus } from "./provider.js";
+/** Metadata only: the host reads these facts before decrypting a credential. */
+export interface MailCredentialFact {
+    readonly id: string;
+    readonly label: string;
+    readonly vaultRevision?: number;
+    readonly updatedAt: string;
+}
+/** Credential presence exposed in configuration reports; never a token or username. */
+export interface MailProviderCredentialFacts {
+    readonly required: boolean;
+    readonly saved: boolean;
+    readonly label?: string;
+    readonly credentialId?: string;
+    readonly updatedAt?: string;
+}
+/** Declarative setup copy belongs to the host or plugin. */
+export interface MailProviderField {
+    readonly key: string;
+    readonly label: string;
+    readonly type: "secret" | "text" | "url" | "email";
+    readonly required: boolean;
+    readonly defaultValue?: string;
+    readonly placeholder?: string;
+    readonly help?: string;
+    readonly helpUrl?: string;
+}
+export interface MailProviderSetup {
+    readonly fields: readonly MailProviderField[];
+    readonly helpUrl?: string;
+}
+/** Safe host-supplied projection; configuration building and product copy stay in the host. */
+export interface MailProviderConfiguration {
+    readonly pluginId?: string;
+    readonly id: string;
+    readonly label: string;
+    readonly origin: "core" | "plugin";
+    readonly hosted: boolean;
+    readonly lanes: readonly ("transactional" | "bulk")[];
+    readonly capabilities: Pick<MailProviderCapabilities, "feedback" | "domainVerification" | "rateLimit">;
+    readonly credential: MailProviderCredentialFacts;
+    readonly selectable: boolean;
+    readonly refusal?: string;
+    readonly setup: MailProviderSetup;
+}
+export interface MailProviderConfigurationReport {
+    readonly setting: MailProviderSetting;
+    readonly providers: readonly MailProviderConfiguration[];
+    readonly refusals: readonly string[];
+}
+/** A provider failure safe for callers; contains neither credentials nor message bodies. */
+export interface MailProviderError {
+    readonly at: string;
+    readonly providerId: string | null;
+    readonly source: "send" | "check";
+    readonly code?: string;
+    readonly message: string;
+}
+/** Alias the provider's existing verdict vocabulary instead of defining another taxonomy. */
+export type ProviderDomainState = MailDomainState;
+/** Provider verification is independent of DNS answers and credential presence. */
+export type SenderDomainVerification = {
+    state: ProviderDomainState;
+    domain: string;
+    providerId: string;
+} | {
+    state: "no_sender";
+    providerId: string | null;
+} | {
+    state: "no_provider";
+    domain: string;
+    providerId: string | null;
+} | {
+    state: "unsupported";
+    domain: string;
+    providerId: string;
+} | {
+    state: "unknown";
+    domain?: string;
+    providerId: string | null;
+    reason: string;
+};
+export interface MailStatusReport extends MailStatus {
+    readonly senderDomainVerification?: SenderDomainVerification;
+    readonly providers: readonly MailProviderConfiguration[];
+    readonly refusals: readonly string[];
+    readonly checkedAt: string;
+    readonly lastError?: MailProviderError;
+}
+export type MailProviderCheck = {
+    ok: true;
+    label: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Host-built catalog: trusted loading, labels and setup copy remain outside the engine. */
+export interface MailProviderCatalog {
+    readonly registry: MailProviderRegistry;
+    readonly pluginIds: readonly string[];
+    readonly refusals: readonly string[];
+    credentialLabelFor(required: {
+        id: string;
+    }): string | undefined;
+    setupFor(required: {
+        id: string;
+    }): MailProviderSetup;
+}
+/** Host settings adapter; reads do not infer provider selection from saved credentials. */
+export interface MailProviderSettingPort {
+    read(required: Record<string, never>): Promise<MailProviderSetting | null>;
+    write(required: {
+        setting: MailProviderSetting;
+    }): Promise<void>;
+}
+/** Host owns metadata lookup and decryption. Metadata may fail independently of key resolution. */
+export interface MailCredentialPort {
+    readFact(required: {
+        label: string;
+    }): Promise<MailCredentialFact | undefined>;
+    resolve(required: {
+        catalog: MailProviderCatalog;
+        id: string;
+    }): Promise<MailAdapterCredential | null>;
+}
+/** Read-only provider verdict; implementations return unknown on lookup/provider failures. */
+export type SenderDomainVerificationPort = () => Promise<SenderDomainVerification>;
+//# sourceMappingURL=engine-contracts.d.ts.map

package/dist/mail/engine-contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=engine-contracts.js.map

package/dist/mail/index.d.ts

@@ -1,8 +1,9 @@
 export type * from "./types.js";
 export type * from "./ports.js";
 export type * from "./adapter-module.js";
-export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
-export type { WrapMailerWithPurposeGateOptions } from "./purpose-scoped-mailer.js";
+export type * from "./engine-contracts.js";
+export { wrapMailerWithPurposeGate, isPurposeGateOpen } from "./purpose-scoped-mailer.js";
+export type { WrapMailerWithPurposeGateOptions, PurposeGateRequired } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
 export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
 export type { ConfiguredMailSender, CreateMailSenderIdentityResolverOptional, MailSenderIdentityPort } from "./sender-identity.js";
@@ -15,4 +16,16 @@ export type { MailDeliveryPolicy, MailDeliveryPolicyDeps, MailDeliveryPolicyOpti
 export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
 export type { MailFeedbackInboxPort, MailFeedbackIngestDeps, MailFeedbackIngestOptions, MailFeedbackResponse } from "./feedback.js";
 export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
+export { safeMailProviderText, credentialSecrets } from "./provider-error.js";
+export { readMailDomain, isDomainReadPermissionRefused } from "./domain-read.js";
+export type { MailDomainReadCredentialPort } from "./domain-read.js";
+export { createSenderDomainVerification } from "./sender-domain-verification.js";
+export type { SenderDomainVerificationDeps } from "./sender-domain-verification.js";
+export { createMailPolicyWrapper } from "./delivery-wrapper.js";
+export type { MailPolicyWrapperDeps, MailPolicyWrapperOptions, MailPolicyWrapperInput } from "./delivery-wrapper.js";
+export { createResolvedMailer } from "./resolve-mailer.js";
+export type { ResolveMailerDeps, ResolveMailerOptions, ResolvedMailer } from "./resolve-mailer.js";
+export { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+export type { TtlCache } from "./mail-status-cache.js";
+export * from "./senders.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/mail/index.js

@@ -1,4 +1,4 @@
-export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
+export { wrapMailerWithPurposeGate, isPurposeGateOpen } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
 export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
 export { createMailProviderRegistry, validateMailProvider, initialMailProviderSetting, computeMailStatus, MAIL_PROVIDER_SETTING_KEY } from "./provider.js";
@@ -6,4 +6,11 @@ export { createMailLaneLimiter } from "./rate-limit.js";
 export { createMailDeliveryPolicy, createPolicyMailer, laneForPurpose, hasOneClickUnsubscribe, mailPayloadHash, MAIL_RATE_LIMITED, isMailRateLimited } from "./policy.js";
 export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
 export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
+export { safeMailProviderText, credentialSecrets } from "./provider-error.js";
+export { readMailDomain, isDomainReadPermissionRefused } from "./domain-read.js";
+export { createSenderDomainVerification } from "./sender-domain-verification.js";
+export { createMailPolicyWrapper } from "./delivery-wrapper.js";
+export { createResolvedMailer } from "./resolve-mailer.js";
+export { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+export * from "./senders.js";
 //# sourceMappingURL=index.js.map

package/dist/mail/mail-status-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file A short-TTL, single-flight cache for the mail status report.
+ * Building the report can call the provider (domain status) and decrypt keys, which took 4–9 s per
+ * admin page load; within the TTL every reader shares one result. `refresh` requests a fresh build,
+ * subject to the optional minimum refresh interval.
+ * `invalidate` drops the cached one (a provider switch or a key save). A failed build is never
+ * cached, and a build that started before an invalidation is not stored over it.
+ */
+/** Default freshness window for mail status. */
+export declare const MAIL_STATUS_TTL_MS = 30000;
+export interface TtlCache<T> {
+    get(optional?: {
+        refresh?: boolean;
+    }): Promise<T>;
+    invalidate(): void;
+}
+/**
+ * @param required.load - Builds a fresh value; its rejection reaches every concurrent caller.
+ * @param required.ttlMs - How long a built value is served.
+ * @param required.nowMs - Injected clock.
+ * @param optional.minRefreshIntervalMs - Ignore forced refresh inside this interval after a build
+ *   starts; zero preserves unrestricted superseding refreshes. Invalidation resets the interval.
+ * @complexity O(1) per call; ordinary reads share one pending load. Explicit refresh may supersede it.
+ * @example const cache = createTtlCache({ load, ttlMs: MAIL_STATUS_TTL_MS, nowMs }); await cache.get();
+ */
+export declare function createTtlCache<T>(required: {
+    load: () => Promise<T>;
+    ttlMs: number;
+    nowMs: () => number;
+}, optional?: {
+    minRefreshIntervalMs?: number;
+}): TtlCache<T>;
+//# sourceMappingURL=mail-status-cache.d.ts.map

package/dist/mail/mail-status-cache.js

@@ -0,0 +1,56 @@
+/**
+ * @file A short-TTL, single-flight cache for the mail status report.
+ * Building the report can call the provider (domain status) and decrypt keys, which took 4–9 s per
+ * admin page load; within the TTL every reader shares one result. `refresh` requests a fresh build,
+ * subject to the optional minimum refresh interval.
+ * `invalidate` drops the cached one (a provider switch or a key save). A failed build is never
+ * cached, and a build that started before an invalidation is not stored over it.
+ */
+/** Default freshness window for mail status. */
+export const MAIL_STATUS_TTL_MS = 30_000;
+/**
+ * @param required.load - Builds a fresh value; its rejection reaches every concurrent caller.
+ * @param required.ttlMs - How long a built value is served.
+ * @param required.nowMs - Injected clock.
+ * @param optional.minRefreshIntervalMs - Ignore forced refresh inside this interval after a build
+ *   starts; zero preserves unrestricted superseding refreshes. Invalidation resets the interval.
+ * @complexity O(1) per call; ordinary reads share one pending load. Explicit refresh may supersede it.
+ * @example const cache = createTtlCache({ load, ttlMs: MAIL_STATUS_TTL_MS, nowMs }); await cache.get();
+ */
+export function createTtlCache(required, optional = {}) {
+    let cached;
+    let inFlight;
+    let generation = 0;
+    let lastBuildAt = -Infinity;
+    const start = () => {
+        lastBuildAt = required.nowMs();
+        const startedIn = generation;
+        const started = required.load().then((value) => {
+            if (startedIn === generation)
+                cached = { value, expiresAt: required.nowMs() + required.ttlMs };
+            return value;
+        }).finally(() => { if (inFlight === started)
+            inFlight = undefined; });
+        inFlight = started;
+        return started;
+    };
+    const minRefreshIntervalMs = optional.minRefreshIntervalMs ?? 0;
+    return {
+        get: async (optional = {}) => {
+            if (optional.refresh && required.nowMs() - lastBuildAt >= minRefreshIntervalMs) {
+                generation += 1;
+                return start();
+            }
+            if (cached && required.nowMs() < cached.expiresAt)
+                return cached.value;
+            return inFlight ?? start();
+        },
+        invalidate: () => {
+            generation += 1;
+            cached = undefined;
+            inFlight = undefined;
+            lastBuildAt = -Infinity;
+        },
+    };
+}
+//# sourceMappingURL=mail-status-cache.js.map

package/dist/mail/prepare-sender-email.d.ts

@@ -0,0 +1,35 @@
+import { type EmailSender, type EmailSourceDescription, type EmailSourceField, type EmailSourceRequest, type EmailTemplatePort } from "./email-sender.js";
+import type { EmailAddress } from "./types.js";
+/** Refuses unsupported declarations and undeclared placeholders before activation or rendering.
+ * @complexity O(f + d + p) source fields, declarations and placeholders; no I/O. */
+export declare function validateEmailSourceTemplate(required: {
+    readonly fields: readonly EmailSourceField[];
+    readonly template: {
+        readonly fields: readonly string[];
+        readonly placeholders: readonly string[];
+    };
+}, _optional?: Record<string, never>): void;
+/** A preparation result is suitable for freezing in the sender's existing job, never a new queue. */
+export interface PreparedSenderEmail {
+    readonly bindingId: string;
+    readonly templateId: string;
+    readonly templateVersion: string;
+    readonly to: EmailAddress;
+    readonly replyTo: EmailAddress;
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    readonly purpose: EmailSourceDescription["purpose"];
+    readonly lane: EmailSourceDescription["lane"];
+    readonly warnings: readonly string[];
+}
+/** Resolves authoritative event data and the saved binding, then calls the existing renderer.
+ * No preview samples, envelope overrides or delivery effects enter this operation.
+ * @throws EmailSenderError for ownership, inactive/pre-activation events, readiness, compatibility or missing data; port errors propagate.
+ * @complexity O(fields + declarations + placeholders); one describe, resolve and render per event. */
+export declare function prepareSenderEmail(required: EmailSourceRequest & {
+    readonly sender: EmailSender;
+    readonly templates: EmailTemplatePort;
+    readonly eventId: string;
+}, _optional?: Record<string, never>): Promise<PreparedSenderEmail>;
+//# sourceMappingURL=prepare-sender-email.d.ts.map

package/dist/mail/prepare-sender-email.js

@@ -0,0 +1,68 @@
+import { EmailSenderError } from "./email-sender.js";
+/** Refuses unsupported declarations and undeclared placeholders before activation or rendering.
+ * @complexity O(f + d + p) source fields, declarations and placeholders; no I/O. */
+export function validateEmailSourceTemplate(required, _optional = {}) {
+    const available = new Set(required.fields.map(field => field.token));
+    const declared = new Set(required.template.fields);
+    if (required.template.fields.some(token => !available.has(token)))
+        throw new EmailSenderError({ code: "incompatible" });
+    if (required.template.placeholders.some(token => !declared.has(token)))
+        throw new EmailSenderError({ code: "incompatible" });
+}
+/** Selects declared values, refusing missing required answers and warning on absent optional ones. */
+function templateValues(required, _optional = {}) {
+    const fields = new Map(required.fields.map(field => [field.token, field]));
+    const warnings = [];
+    const values = Object.fromEntries(required.tokens.map(token => {
+        const value = Object.hasOwn(required.values, token) ? required.values[token] : undefined;
+        if (typeof value === "string" && value !== "")
+            return [token, value];
+        if (fields.get(token)?.required)
+            throw new EmailSenderError({ code: "missing_value" });
+        warnings.push(token);
+        return [token, ""];
+    }));
+    return { values, warnings };
+}
+/** Resolves only a source-permitted recipient; configuration and missing answers fail separately.
+ * @complexity O(permitted choices + resolved recipients); no I/O. */
+function recipientAddress({ source, resolved, recipientId }, _optional = {}) {
+    if (!source.permittedRecipients.some(choice => choice.id === recipientId))
+        throw new EmailSenderError({ code: "configuration" });
+    const recipient = resolved.recipients.find(choice => choice.id === recipientId);
+    if (!recipient)
+        throw new EmailSenderError({ code: "missing_value" });
+    return recipient.address;
+}
+/** Resolves authoritative event data and the saved binding, then calls the existing renderer.
+ * No preview samples, envelope overrides or delivery effects enter this operation.
+ * @throws EmailSenderError for ownership, inactive/pre-activation events, readiness, compatibility or missing data; port errors propagate.
+ * @complexity O(fields + declarations + placeholders); one describe, resolve and render per event. */
+export async function prepareSenderEmail(required, _optional = {}) {
+    const { sender, templates, workspaceId, principalId, sourceId, eventId } = required;
+    const context = { workspaceId, principalId, sourceId };
+    const source = await sender.describeSource(context);
+    if (source.senderId !== sender.id || source.sourceId !== sourceId)
+        throw new EmailSenderError({ code: "ownership" });
+    const binding = source.binding;
+    if (!binding?.enabled)
+        throw new EmailSenderError({ code: "configuration" });
+    if (!source.readiness.ready)
+        throw new EmailSenderError({ code: "not_ready" });
+    const templateContext = { workspaceId, principalId, templateId: binding.templateId };
+    const template = await templates.describe(templateContext);
+    validateEmailSourceTemplate({ fields: source.fields, template });
+    const resolved = await sender.resolveEvent({ ...context, eventId });
+    // MOVE: Compare against the latest activation so re-enabling cannot revive a backlog.
+    if (!binding.activatedAt || !(Date.parse(resolved.occurredAt) >= Date.parse(binding.activatedAt)))
+        throw new EmailSenderError({ code: "configuration" });
+    const to = recipientAddress({ source, resolved, recipientId: binding.recipientId });
+    const { values, warnings } = templateValues({ fields: source.fields, tokens: template.fields, values: resolved.values });
+    const rendered = await templates.render({ ...templateContext, version: template.version, values });
+    if (rendered.missingFields.length > 0)
+        throw new EmailSenderError({ code: "missing_value" });
+    return { bindingId: binding.bindingId, templateId: binding.templateId, templateVersion: template.version, to,
+        replyTo: { email: binding.replyTo }, subject: rendered.subject, html: rendered.html, text: rendered.text,
+        purpose: source.purpose, lane: source.lane, warnings };
+}
+//# sourceMappingURL=prepare-sender-email.js.map

package/dist/mail/provider-error.d.ts

@@ -0,0 +1,18 @@
+/** Provider diagnostics cross the host boundary only after Jini's secret scrubber, then a cap.
+ * Exact credential values are supplied where available; redaction precedes truncation so a token
+ * crossing the length boundary cannot leave a readable prefix. Mail also masks URL token parameters
+ * (including fragments) through Jini's caller-owned patterns.
+ * @complexity O(n) in diagnostic text for a bounded set of credential values; output <= 1000 chars.
+ */
+export declare function safeMailProviderText({ text }: {
+    text: string;
+}, { secrets }?: {
+    secrets?: readonly string[];
+}): string;
+/** The credential's string values, so exact redaction also catches keys no pattern recognises.
+ * @complexity O(k) credential fields.
+ */
+export declare function credentialSecrets({ credential }: {
+    credential: object;
+}, _options?: Record<string, never>): string[];
+//# sourceMappingURL=provider-error.d.ts.map

package/dist/mail/provider-error.js

@@ -0,0 +1,24 @@
+import { redactSecrets } from "@jini-ai/core";
+/** Provider diagnostics cross the host boundary only after Jini's secret scrubber, then a cap.
+ * Exact credential values are supplied where available; redaction precedes truncation so a token
+ * crossing the length boundary cannot leave a readable prefix. Mail also masks URL token parameters
+ * (including fragments) through Jini's caller-owned patterns.
+ * @complexity O(n) in diagnostic text for a bounded set of credential values; output <= 1000 chars.
+ */
+export function safeMailProviderText({ text }, { secrets = [] } = {}) {
+    return redactSecrets({ input: text }, {
+        exactSecrets: secrets,
+        redactPii: false,
+        // Any secret-shaped URL parameter (token, key, secret, signature, code, password), not only `token=`:
+        // provider errors echo whole request URLs, and the parameter name varies by provider. The value runs
+        // to the next `&` so a trailing `#fragment` is masked with it.
+        extraPatterns: [{ name: "url_secret_param", regex: /[?&#;][\w.-]*(?:token|key|secret|signature|sig|code|password|pwd|auth)[\w.-]*=[^&\s"'<>]+/gi }],
+    }).slice(0, 1000);
+}
+/** The credential's string values, so exact redaction also catches keys no pattern recognises.
+ * @complexity O(k) credential fields.
+ */
+export function credentialSecrets({ credential }, _options = {}) {
+    return Object.values(credential).filter((value) => typeof value === "string");
+}
+//# sourceMappingURL=provider-error.js.map

package/dist/mail/purpose-scoped-mailer.d.ts

@@ -1,13 +1,24 @@
 /** Unknown and absent lanes require a durable notification path in production.
  * Local mode and explicit interactive sends proceed without that gate.
  */
-import type { MailerPort, DeliveryReadinessPolicy } from "./ports.js";
+import type { MailerPort, MailerSendOptions, DeliveryReadinessPolicy } from "./ports.js";
 type RuntimeMode = "production" | "local";
 export interface WrapMailerWithPurposeGateOptions {
     inner: MailerPort;
     mode: RuntimeMode;
     readiness: DeliveryReadinessPolicy;
 }
+export interface PurposeGateRequired {
+    mode: RuntimeMode;
+    readiness: DeliveryReadinessPolicy;
+    options: Pick<MailerSendOptions, "lane" | "sourceContext">;
+}
+/**
+ * Ask the delivery gate without delivering: unknown/absent lanes require durable readiness.
+ * Invalid modes throw TypeError; readiness errors propagate so callers can report unknown.
+ * @complexity O(1), with at most one call to the supplied readiness predicate.
+ */
+export declare function isPurposeGateOpen(required: PurposeGateRequired): boolean;
 /** Validates the mode at wrap time and gates notification sends/batches before delivery.
  * Unknown modes throw TypeError; only explicit local mode bypasses durable readiness.
  * @complexity O(1) policy work per send/batch, before delegating delivery.

package/dist/mail/purpose-scoped-mailer.js

@@ -9,6 +9,25 @@ function resolveLane(options) {
 function refusalError(capabilityName) {
     return new Error(`MAILER_SEND_REFUSED_NO_DURABLE_PATH: notification-lane mailer send refused for capability "${capabilityName}" — no durable outbox path registered`);
 }
+function validateMode(mode) {
+    if (mode !== "production" && mode !== "local") {
+        throw new TypeError('mailer mode must be "production" or "local"');
+    }
+}
+/**
+ * Ask the delivery gate without delivering: unknown/absent lanes require durable readiness.
+ * Invalid modes throw TypeError; readiness errors propagate so callers can report unknown.
+ * @complexity O(1), with at most one call to the supplied readiness predicate.
+ */
+export function isPurposeGateOpen(required) {
+    const { mode, readiness, options } = required;
+    validateMode(mode);
+    if (mode === "local")
+        return true;
+    if (resolveLane(options) !== "notification")
+        return true;
+    return readiness.isReady({ capabilityName: options.sourceContext?.module ?? "unknown" });
+}
 // Decorate the existing port rather than inventing a second delivery contract. The caller resolves
 // mode once at composition; never re-read the environment per send and change policy mid-process.
 /** Validates the mode at wrap time and gates notification sends/batches before delivery.
@@ -18,19 +37,11 @@ function refusalError(capabilityName) {
  */
 export function wrapMailerWithPurposeGate(options) {
     const { inner, mode, readiness } = options;
-    // Validate once at composition: typos must never silently disable durable delivery.
-    if (mode !== "production" && mode !== "local") {
-        throw new TypeError('mailer mode must be "production" or "local"');
-    }
+    // Validate at composition: typos must never silently disable durable delivery.
+    validateMode(mode);
     function checkGate(sendOptions) {
-        if (mode === "local")
-            return; // Local mode never refuses delivery.
-        const lane = resolveLane(sendOptions);
-        if (lane !== "notification")
-            return;
-        const capabilityName = sendOptions.sourceContext?.module ?? "unknown";
-        if (!readiness.isReady({ capabilityName })) {
-            throw refusalError(capabilityName);
+        if (!isPurposeGateOpen({ mode, readiness, options: sendOptions })) {
+            throw refusalError(sendOptions.sourceContext?.module ?? "unknown");
         }
     }
     return {

package/dist/mail/resolve-mailer.d.ts

@@ -0,0 +1,95 @@
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { DomainRequirement } from "@jini-ai/core/provider-registry";
+import type { MailAdapterCredential } from "./adapter-module.js";
+import { type MailDomainReadCredentialPort } from "./domain-read.js";
+import type { MailCredentialFact, MailCredentialPort, MailProviderCatalog, MailProviderCheck, MailProviderConfigurationReport, MailProviderSettingPort, MailStatusReport, SenderDomainVerificationPort } from "./engine-contracts.js";
+import type { MailDeliveryLane, MailerPort } from "./ports.js";
+import { type MailProviderModule, type MailProviderSetting } from "./provider.js";
+/** Required host boundaries. HTTP is passed through unchanged; the engine never calls it. */
+export interface ResolveMailerDeps<TRecord extends MailCredentialFact = MailCredentialFact> {
+    workspaceId: string;
+    mode: "local" | "production";
+    providerSetting: MailProviderSettingPort;
+    credentials: MailCredentialPort;
+    /** Metadata only. Preserve the host's row shape for its projection (e.g. SMTP username presence);
+     * the engine only interprets the separate readFact fingerprint. No decryption here. */
+    listCredentialFacts: (required: Record<string, never>) => Promise<readonly TRecord[]>;
+    loadCatalog: (required: Record<string, never>) => Promise<MailProviderCatalog>;
+    httpClient: HttpClientPort;
+    /** Host retains provider ABI binding and credential-aware scrubbing of results/throws. */
+    createProviderMailer: (required: {
+        provider: MailProviderModule;
+        credential: MailAdapterCredential;
+    }) => MailerPort;
+    /** Synchronous safe DTO projection; labels, setup forms and product copy stay in the host. */
+    describeProviders: (required: {
+        catalog: MailProviderCatalog;
+        records: readonly TRecord[];
+        setting: MailProviderSetting;
+    }) => MailProviderConfigurationReport;
+    unconfiguredMessage: (required: {
+        lane: MailDeliveryLane;
+    }) => string;
+    missingCredentialReason: (required: {
+        label: string;
+    }) => string;
+    credentialFailureReason: (required: {
+        label: string;
+        err: unknown;
+    }) => string;
+}
+export interface ResolveMailerOptions {
+    /** Delivery policy decorator; identity when absent. */
+    wrapProviderMailer?: (required: {
+        providerId: string;
+        provider: MailProviderModule;
+        mailer: MailerPort;
+    }) => MailerPort;
+    readSenderEmail?: () => Promise<string | undefined>;
+    resolveDomainReadCredential?: MailDomainReadCredentialPort;
+    warn?: (message: string) => void;
+    clock?: {
+        nowMs(): number;
+    };
+    statusTtlMs?: number;
+    domainRequirementsTimeoutMs?: number;
+}
+/** The control surface remains stable across host adoption, including invalidate on setting writes. */
+export interface ResolvedMailer {
+    /** Safe to use immediately; each send awaits its lane's resolution. */
+    mailer: MailerPort;
+    /** Resolves once the initial setting + transactional resolution settle (a test seam). */
+    ready: Promise<void>;
+    /** Refreshes unresolved configuration and awaits the current driver without sending. */
+    settle: () => Promise<void>;
+    /** Cached briefly; `refresh` rebuilds. Each report carries `checkedAt` and the live `lastError`. */
+    status: (optional?: {
+        refresh?: boolean;
+    }) => Promise<MailStatusReport>;
+    /** The host's safe per-provider configuration DTO. Never a secret. */
+    describeProviders: () => Promise<MailProviderConfigurationReport>;
+    /** Drops cached provider mailers and the cached status; the next send and read resolve fresh. */
+    invalidate: () => void;
+    laneReady: (required: {
+        lane: MailDeliveryLane;
+    }) => Promise<boolean>;
+    senderDomainVerification: SenderDomainVerificationPort;
+    /** Whether `id` may be selected: a registered hosted provider whose saved key resolves. Sends nothing. */
+    checkProvider: (required: {
+        id: string;
+    }) => Promise<MailProviderCheck>;
+    /** Null for another workspace, absent sender/provider/key or unsupported verification.
+     * Provider failures throw caller-safe ToolInputError; the deadline throws Error. */
+    domainRequirements: (required: {
+        workspaceId: string;
+    }) => Promise<DomainRequirement | null>;
+}
+/**
+ * Build a lane router and its control surface. The host binds catalogs, secrets, safe copy and DTOs.
+ * Each send reads selection and metadata; boot starts resolution synchronously. Selection faults
+ * refuse safely; status/description setup faults propagate and are never cached.
+ * @complexity O(providers) cached mailers/flights; status holds one report for its TTL.
+ * @example const control = createResolvedMailer(hostPorts, { clock }); await control.ready;
+ */
+export declare function createResolvedMailer<TRecord extends MailCredentialFact = MailCredentialFact>(required: ResolveMailerDeps<TRecord>, optional?: ResolveMailerOptions): ResolvedMailer;
+//# sourceMappingURL=resolve-mailer.d.ts.map