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

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/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

package/dist/mail/resolve-mailer.js

@@ -0,0 +1,348 @@
+/**
+ * Explicit lane selection, live credential rotation and cached provider status.
+ * Saved keys never select a provider. Local fallback uses the catalog's console provider;
+ * production refuses. Host ports retain trusted loading, credential copy and configuration DTOs.
+ * capabilities() is synchronous and reports console until transactional resolution settles;
+ * sends always await their own lane. Invalidation detaches obsolete work without cancelling it.
+ */
+import { ToolInputError } from "@jini-ai/core";
+import { readMailDomain } from "./domain-read.js";
+import { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+import { credentialSecrets, safeMailProviderText } from "./provider-error.js";
+import { computeMailStatus, initialMailProviderSetting } from "./provider.js";
+import { laneForPurpose } from "./policy.js";
+import { createSenderDomainVerification } from "./sender-domain-verification.js";
+const CONSOLE_CAPABILITIES = { driver: "console", supportsIdempotencyKey: false, supportsWebhookFeedback: false, maxBatchSize: 1, supportsAttachments: true };
+/** Metadata identifies the exact saved version without decryption. @complexity O(1). */
+function rowFingerprint(record) {
+    return record ? `${record.id}:${record.vaultRevision ?? ""}:${record.updatedAt}` : "absent";
+}
+/** Any failed recipient wins; only a wholly accepted, nonempty operation clears a send failure.
+ * Results and exceptions pass through unchanged. @complexity O(messages) time, O(1) space. */
+function observeFailures(required) {
+    const { mailer, providerId, record, accepted } = required;
+    const seen = (results) => {
+        const failure = results.find(result => !result.ok);
+        if (failure && !failure.ok) {
+            record({ providerId, source: "send", code: failure.errorCode, message: failure.message });
+            return;
+        }
+        if (results.length > 0)
+            accepted();
+    };
+    return {
+        capabilities: () => mailer.capabilities({}),
+        send: async (input, options) => { const result = await mailer.send(input, options); seen([result]); return result; },
+        sendBatch: async (input, options) => { const results = await mailer.sendBatch(input, options); seen(results); return results; },
+    };
+}
+/** Refusals report console so availability checks never mistake them for delivery. @complexity O(messages) for batches. */
+function refusingMailer(required) {
+    const result = { ok: false, retryable: false, errorCode: required.errorCode, message: required.message };
+    return { capabilities: () => CONSOLE_CAPABILITIES, send: async () => result, sendBatch: async ({ messages }) => messages.map(() => result) };
+}
+/** Diagnostic sinks cannot throw across the mail boundary; production warns once per reason. */
+function warnOnce({ state, key, message }) {
+    if (state.deps.mode !== "production" || state.warned.has(key))
+        return;
+    state.warned.add(key);
+    try {
+        state.warn(message);
+    }
+    catch { /* Diagnostics cannot reject a send. */ }
+}
+/** Never retain provider/body details. Repeated checks must not hide a failed send. */
+function recordError({ state, error }) {
+    const { providerId, source } = error;
+    if (source === "check" && state.lastError?.source === "send")
+        return;
+    state.lastError = { providerId, source, message: source === "send" ? "The provider did not confirm acceptance. Check provider configuration." : "The provider configuration check could not complete.", at: new Date(state.nowMs()).toISOString() };
+}
+/** First boot remains unconfigured even with saved keys; failed persistence is retried on a later read. */
+async function initialize(state) {
+    const setting = initialMailProviderSetting({});
+    await state.deps.providerSetting.write({ setting }).catch(() => warnOnce({ state, key: "initialization", message: "[mail] the mail provider setting could not be saved; retrying on the next send" }));
+    return setting;
+}
+/** Only initialization is single-flight: every call still reads the current selection first. */
+async function currentSetting(state) {
+    const stored = await state.deps.providerSetting.read({});
+    if (stored)
+        return stored;
+    state.initialization ??= initialize(state).finally(() => { state.initialization = undefined; });
+    return state.initialization;
+}
+/** Keyless providers never touch the credential metadata store. */
+async function fingerprintFor({ state, label }) {
+    if (label === undefined)
+        return "";
+    return rowFingerprint(await state.deps.credentials.readFact({ label }));
+}
+/** The host catalog guarantees the built-in console provider. Its mailer shares the policy wrapper. */
+async function consoleMailer({ state, catalog }) {
+    const provider = catalog.registry.get({ id: "console" }).provider;
+    const mailer = state.wrap({ providerId: "console", provider, mailer: state.deps.createProviderMailer({ provider, credential: { token: "" } }) });
+    state.resolved.set("console", { mailer, fingerprint: "" });
+    return mailer;
+}
+/** Local mode keeps working through console; production refuses and logs safe host copy once. */
+async function fallback(required) {
+    const { state } = required;
+    if (state.deps.mode !== "production")
+        return state.resolved.get("console")?.mailer ?? consoleMailer(required);
+    warnOnce({ state, key: required.errorCode + required.message, message: required.message });
+    return refusingMailer(required);
+}
+/** A missing key or failed decrypt uses the host's established caller-safe refusal wording. */
+async function credentialOrReason({ state, catalog, id, label }) {
+    try {
+        const credential = await state.deps.credentials.resolve({ catalog, id });
+        if (credential)
+            return { credential };
+    }
+    catch (err) {
+        return { reason: state.deps.credentialFailureReason({ label, err }) };
+    }
+    return { reason: state.deps.missingCredentialReason({ label }) };
+}
+/** A catalog label means a saved key is required; keyless providers receive an empty token. */
+function providerCredential({ state, catalog, id }) {
+    const label = catalog.credentialLabelFor({ id });
+    return label === undefined ? Promise.resolve({ credential: { token: "" } }) : credentialOrReason({ state, catalog, id, label });
+}
+/** Preserve provider selection refusals, including the catalog's trusted plugin-load diagnostics. */
+function unavailable(required) {
+    return fallback({ ...required, errorCode: "MAIL_PROVIDER_UNAVAILABLE", message: `[mail] the selected mail provider '${required.id}' ${required.detail}, so outbound mail is NOT being sent` });
+}
+/** A successful operation only clears a failure from the same provider. */
+function acceptProvider({ state, id }) {
+    if (state.lastError?.source === "send" && state.lastError.providerId === id)
+        state.lastError = undefined;
+}
+/** Construct only after metadata/key/metadata agree; a generation change prevents caching obsolete work.
+ * @complexity One catalog load, two metadata reads and one decrypt per attempt; races retry in order. */
+async function resolveProvider({ state, id, startedIn }) {
+    const catalog = await state.deps.loadCatalog({});
+    const entry = catalog.registry.get({ id });
+    if (!entry) {
+        const refusals = catalog.refusals.length > 0 ? ` (${catalog.refusals.join("; ")})` : "";
+        return unavailable({ state, catalog, id, detail: `is not installed${refusals}` });
+    }
+    // Fingerprint BEFORE reading the key: a rotation racing this read then re-resolves next send.
+    // An unreadable store leaves key lookup to report why; "unknown" re-resolves once it reads.
+    const label = catalog.credentialLabelFor({ id });
+    const fingerprint = await fingerprintFor({ state, label }).catch(() => "unknown");
+    const found = await providerCredential({ state, catalog, id });
+    if (!found.credential)
+        return unavailable({ state, catalog, id, detail: found.reason });
+    const credential = found.credential;
+    const latest = await fingerprintFor({ state, label }).catch(() => fingerprint);
+    if (latest !== fingerprint)
+        return resolveProvider({ state, id, startedIn: state.generation });
+    const observed = observeFailures({ mailer: state.deps.createProviderMailer({ provider: entry.provider, credential }), providerId: id,
+        record: error => recordError({ state, error }), accepted: () => acceptProvider({ state, id }) });
+    const mailer = state.wrap({ providerId: id, provider: entry.provider, mailer: observed });
+    if (startedIn === state.generation)
+        state.resolved.set(id, { mailer, fingerprint, ...(label === undefined ? {} : { label }) });
+    return mailer;
+}
+/** Boot and early sends share one resolution per provider. Old completions rejoin the current generation. */
+function resolveOnce({ state, id }) {
+    const existing = state.inFlight.get(id);
+    if (existing)
+        return existing;
+    const startedIn = state.generation;
+    const started = resolveProvider({ state, id, startedIn }).then(mailer => startedIn === state.generation ? mailer : resolveOnce({ state, id }))
+        .finally(() => { if (state.inFlight.get(id) === started)
+        state.inFlight.delete(id); });
+    state.inFlight.set(id, started);
+    return started;
+}
+/** Reuse unchanged rows; metadata faults keep a usable cached mailer. @complexity One metadata read per send. */
+async function currentMailer({ state, id }) {
+    const entry = state.resolved.get(id);
+    if (!entry)
+        return resolveOnce({ state, id });
+    if (entry.label === undefined)
+        return entry.mailer;
+    const fingerprint = await fingerprintFor({ state, label: entry.label }).catch(() => entry.fingerprint);
+    if (fingerprint === entry.fingerprint)
+        return entry.mailer;
+    if (state.resolved.get(id) === entry)
+        state.resolved.delete(id);
+    return resolveOnce({ state, id });
+}
+/** Fresh lane selection precedes every resolution and updates the synchronous transactional projection. */
+async function mailerForLane({ state, lane }) {
+    const id = (await currentSetting(state))[lane];
+    const mailer = id === null
+        ? await fallback({ state, catalog: await state.deps.loadCatalog({}), errorCode: "MAIL_UNCONFIGURED", message: state.deps.unconfiguredMessage({ lane }) })
+        : await currentMailer({ state, id });
+    if (lane === "transactional")
+        state.lastTransactional = mailer;
+    return mailer;
+}
+/** Settings/catalog faults become a refusal rather than throwing across the routing boundary. */
+function forLane(required) {
+    return mailerForLane(required).catch(() => refusingMailer({ errorCode: "MAIL_PROVIDER_UNAVAILABLE", message: "Mail provider selection failed; check configuration." }));
+}
+/** The public mailer preserves synchronous capability reporting and awaits the proper lane for sends. */
+function createRouter(state) {
+    return {
+        capabilities: () => {
+            if (state.lastTransactional === undefined)
+                void forLane({ state, lane: "transactional" });
+            return state.lastTransactional?.capabilities({}) ?? CONSOLE_CAPABILITIES;
+        },
+        send: async (input, options = {}) => (await forLane({ state, lane: laneForPurpose({ purpose: options.purpose }) })).send(input, options),
+        sendBatch: async (input, options = {}) => (await forLane({ state, lane: laneForPurpose({ purpose: options.purpose }) })).sendBatch(input, options),
+    };
+}
+/** Sender settings errors count as unset; parsing retains the original lowercase/trim behavior. */
+async function readSenderDomain(state) {
+    const email = await state.options.readSenderEmail?.().catch(() => undefined);
+    return email?.split("@")[1]?.trim().toLowerCase() || undefined;
+}
+/** Domain status shares selection/credentials with delivery, while keeping its own ordered reads. */
+function createDomainVerification({ state, resolveDomainReadCredential }) {
+    return createSenderDomainVerification({
+        workspaceId: state.deps.workspaceId, httpClient: state.deps.httpClient,
+        findProvider: async ({ id }) => (await state.deps.loadCatalog({})).registry.get({ id })?.provider,
+        resolveCredential: async ({ id }) => state.deps.credentials.resolve({ catalog: await state.deps.loadCatalog({}), id }),
+        resolveDomainReadCredential,
+        readProviderId: async () => (await currentSetting(state)).transactional,
+        readSenderEmail: async () => state.options.readSenderEmail ? state.options.readSenderEmail() : undefined,
+    });
+}
+/** Separate requirements read with permission-only fallback; deadline covers provider calls, not setup.
+ * Registry validation guarantees domainRequirements when domainVerification is true.
+ * @complexity At most two provider calls; diagnostic output is capped at 1000 characters. */
+async function requestDomainRequirements(required, optional = {}) {
+    const { ctx, providerId, provider, domain } = required;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error("The mail provider could not list its required DNS records.")), optional.timeoutMs ?? 5_000);
+    });
+    try {
+        const result = await Promise.race([readMailDomain({ ctx, providerId, read: context => provider.domainRequirements(context, { domain }), resolveDomainReadCredential: required.resolveDomainReadCredential }), timeout]);
+        if (result.status === "ok")
+            return result.value;
+        throw new ToolInputError({ message: safeMailProviderText({ text: `${result.error.code}: ${result.error.message}` }, { secrets: credentialSecrets({ credential: ctx.credential }) }) });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Resolve requirements only for this workspace and its active transactional provider. */
+async function domainRequirements(required) {
+    const { state, resolveDomainReadCredential } = required;
+    if (required.workspaceId !== state.deps.workspaceId)
+        return null;
+    const [setting, catalog, domain] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), readSenderDomain(state)]);
+    const id = setting.transactional;
+    const provider = id === null ? undefined : catalog.registry.get({ id })?.provider;
+    if (!domain || !provider?.capabilities.domainVerification)
+        return null;
+    const { credential } = await providerCredential({ state, catalog, id: id });
+    const ctx = credential ? { workspaceId: state.deps.workspaceId, mode: "live", credential, httpClient: state.deps.httpClient } : null;
+    return ctx ? requestDomainRequirements({ ctx, providerId: id, provider, domain, resolveDomainReadCredential }, { timeoutMs: state.options.domainRequirementsTimeoutMs }) : null;
+}
+/** Unique lane keys resolve in parallel; each failed lookup records a safe check note. @complexity O(lanes). */
+async function laneCredentials(required) {
+    const { state, catalog, setting } = required;
+    const ids = [...new Set([setting.transactional, setting.bulk].filter((id) => id !== null))];
+    const lookup = (id) => state.deps.credentials.resolve({ catalog, id }).catch((err) => {
+        // Only a provider with a label reaches the store, so a thrown lookup has a defined label.
+        recordError({ state, error: { providerId: id, source: "check", message: state.deps.credentialFailureReason({ label: catalog.credentialLabelFor({ id }), err }) } });
+        return null;
+    });
+    const found = await Promise.all(ids.map(async (id) => [id, await lookup(id)]));
+    return new Map(found.filter((pair) => pair[1] !== null));
+}
+/** Row-list faults affect presence facts but do not prevent independent key resolution. */
+function statusCredentialFacts({ state, deps }) {
+    return deps.listCredentialFacts({}).catch((err) => {
+        recordError({ state, error: { providerId: null, source: "check", message: `the saved mail credentials could not be listed (${err instanceof Error ? err.message : String(err)})` } });
+        return [];
+    });
+}
+/** Unanswered/unsupported checks produce no sender warning; only no_sender means unset. */
+function statusDomainState(state) {
+    if (state === "no_sender")
+        return null;
+    return ["verified", "pending", "failed", "not_found"].includes(state) ? state : undefined;
+}
+/** Start independent reads together, then await lane keys and domain verification in that order.
+ * Null means no sender; an unanswered check stays undefined and must not claim a sender is missing.
+ * @complexity O(c + p) credential facts/providers, O(lanes) decrypts; domain work uses its own deadline. */
+async function computeStatusReport(required) {
+    const { state, deps, senderDomainVerification } = required;
+    const checkedAt = new Date(state.nowMs()).toISOString();
+    const records = statusCredentialFacts({ state, deps });
+    const [setting, catalog, rows] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), records, readSenderDomain(state)]);
+    const credentials = await laneCredentials({ state, catalog, setting });
+    const verdict = await senderDomainVerification();
+    const domainState = statusDomainState(verdict.state);
+    if (verdict.state === "unknown")
+        recordError({ state, error: { providerId: verdict.providerId, source: "check", message: "Provider domain check unavailable." } });
+    const status = computeMailStatus({ setting, registry: catalog.registry, hasCredential: id => credentials.has(id) }, domainState === undefined ? {} : { senderDomainState: domainState });
+    const { providers } = deps.describeProviders({ catalog, records: rows, setting });
+    return { ...status, providers, refusals: catalog.refusals, checkedAt, senderDomainVerification: verdict };
+}
+/** Failed sends overlay cached status immediately; configuration alone never proves sending. */
+function statusWithLastError({ state, report }) {
+    const sendFailed = state.lastError?.source === "send" && report.lanes.some(lane => lane.providerId === state.lastError?.providerId);
+    return state.lastError ? { ...report, state: sendFailed && report.state === "ready" ? "degraded" : report.state, lastError: state.lastError } : report;
+}
+/** Host descriptions receive fresh, parallel setting/catalog/metadata reads. Failures propagate. */
+async function describeProviders({ state, deps }) {
+    const [setting, catalog, records] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), deps.listCredentialFacts({})]);
+    return deps.describeProviders({ catalog, records, setting });
+}
+/** Selection checks require a hosted provider and a usable key; they send nothing. */
+async function checkProvider({ state, id }) {
+    const catalog = await state.deps.loadCatalog({});
+    const provider = catalog.registry.get({ id })?.provider;
+    if (!provider)
+        return { ok: false, reason: `'${id}' is not an installed mail provider (installed: ${catalog.registry.list().map(entry => entry.id).join(", ")})` };
+    if (!provider.capabilities.hosted)
+        return { ok: false, reason: `'${id}' only prints mail locally and never delivers it` };
+    const found = await providerCredential({ state, catalog, id });
+    return found.credential ? { ok: true, label: provider.label } : { ok: false, reason: `'${id}' ${found.reason}` };
+}
+/** Detach pending work and clear all provider/capability projections; errors retain their original precedence. */
+function invalidate(state) {
+    state.generation += 1;
+    state.inFlight.clear();
+    state.resolved.clear();
+    state.lastTransactional = undefined;
+}
+/**
+ * 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 function createResolvedMailer(required, optional = {}) {
+    const state = { deps: required, options: optional, nowMs: () => (optional.clock ?? { nowMs: () => Date.now() }).nowMs(),
+        warn: optional.warn ?? (message => console.warn(message)),
+        wrap: optional.wrapProviderMailer ?? (({ mailer }) => mailer), resolved: new Map(), inFlight: new Map(), warned: new Set(), generation: 0,
+        initialization: undefined, lastTransactional: undefined, lastError: undefined };
+    const ready = forLane({ state, lane: "transactional" }).then(() => undefined);
+    const mailer = createRouter(state);
+    const resolveDomainReadCredential = input => optional.resolveDomainReadCredential?.(input) ?? Promise.resolve(null);
+    const senderDomainVerification = createDomainVerification({ state, resolveDomainReadCredential });
+    const statusCache = createTtlCache({ load: () => computeStatusReport({ state, deps: required, senderDomainVerification }), ttlMs: optional.statusTtlMs ?? MAIL_STATUS_TTL_MS, nowMs: state.nowMs }, { minRefreshIntervalMs: 5_000 });
+    return {
+        mailer, ready, senderDomainVerification,
+        settle: async () => { await forLane({ state, lane: "transactional" }); },
+        status: async (options = {}) => statusWithLastError({ state, report: await statusCache.get(options) }),
+        describeProviders: () => describeProviders({ state, deps: required }),
+        invalidate: () => { invalidate(state); statusCache.invalidate(); },
+        laneReady: async ({ lane }) => (await forLane({ state, lane })).capabilities({}).driver !== "console",
+        checkProvider: input => checkProvider({ state, ...input }),
+        domainRequirements: input => domainRequirements({ state, ...input, resolveDomainReadCredential }),
+    };
+}
+//# sourceMappingURL=resolve-mailer.js.map

package/dist/mail/senders.d.ts

@@ -0,0 +1,5 @@
+/** Universal sender surface: importing it never loads SMTP, delivery policy or Node crypto. */
+export * from "./email-sender.js";
+export * from "./email-sender-registry.js";
+export * from "./prepare-sender-email.js";
+//# sourceMappingURL=senders.d.ts.map

package/dist/mail/senders.js

@@ -0,0 +1,5 @@
+/** Universal sender surface: importing it never loads SMTP, delivery policy or Node crypto. */
+export * from "./email-sender.js";
+export * from "./email-sender-registry.js";
+export * from "./prepare-sender-email.js";
+//# sourceMappingURL=senders.js.map

package/dist/secrets/credential-sets/vault.repo.memory.d.ts

@@ -24,10 +24,7 @@ export declare class InMemoryVaultRepo implements VaultRepoPort {
     /** O(n) memory scan, n stored rows; clones only the default, never its siblings. */
     findDefault(input: VaultDefaultQuery, _options?: VaultOptions): Promise<VaultRecord | null>;
     list(input: VaultQuery, _options?: VaultOptions): Promise<VaultRecord[]>;
-    put(input: {
-        record: VaultRecord;
-        expectedRevision: number | null;
-    }, _options?: VaultOptions): Promise<VaultRecord>;
+    put(input: Parameters<VaultRepoPort["put"]>[0], _options?: VaultOptions): Promise<VaultRecord>;
     /** Synchronous mutation owner shared with batch staging; default moves never re-seal. */
     private putRecord;
     patchMeta(input: {

package/dist/secrets/credential-sets/vault.repo.memory.js

@@ -81,7 +81,9 @@ export class InMemoryVaultRepo {
         const group = this.groupRows({ groupKey });
         if (group.some(row => row.id !== record.id && row.label === record.label))
             throw new VaultError({ code: "conflict" });
-        const saved = structuredClone({ ...record, isDefault: record.isDefault || group.length === 0 });
+        // Auto-select the first row so an ordinary save is usable without a separate default action.
+        // Explicit false opts out, keeping unattached project keys from becoming vendor defaults.
+        const saved = structuredClone({ ...record, isDefault: record.isDefault ?? (group.length === 0) });
         // Clear first, matching a SQL partial UNIQUE index; no transient duplicate default is required.
         if (saved.isDefault)
             this.clearDefaults({ group });

package/dist/secrets/credential-sets/vault.service.d.ts

@@ -1,5 +1,5 @@
 import type { KeyringPort, SecretSealerPort } from "../ports.js";
-import { type VaultContext, type VaultIdentity, type VaultMeta, type VaultMetaParsers, type VaultCopyResult, type VaultDefaultQuery, type VaultOptions, type VaultQuery, type VaultRecord, type VaultRepoPort, type VaultSummary } from "./vault.types.js";
+import { type VaultContext, type VaultIdentity, type VaultMeta, type VaultMetaParsers, type VaultCopyResult, type VaultDefaultQuery, type VaultOptions, type VaultQuery, type VaultPutRecord, type VaultRepoPort, type VaultSummary } from "./vault.types.js";
 export interface VaultServiceDeps {
     repo: VaultRepoPort;
     keyring: KeyringPort;
@@ -24,10 +24,10 @@ export interface VaultPutInput extends VaultContext {
      * Creation requires a payload (which may be null). Payloads are always sealed JSON.
      */
     payload?: VaultMeta | null | undefined;
-    /** Omitted preserves same-group default status; a provider move starts with false and the
-     * repository applies its first-row rule. Explicit true selects the destination default.
+    /** Omitted preserves same-group default status; creation/provider moves let the repository
+     * apply its first-row rule. Explicit false opts out; true selects the destination default.
      */
-    isDefault?: boolean;
+    isDefault?: boolean | undefined;
     /** A host-selected token, never a URI or serialized connection object. */
     hintToken?: string;
 }
@@ -50,6 +50,7 @@ export declare class SecretsVaultService {
     constructor(deps: VaultServiceDeps, _options?: VaultOptions);
     private authorize;
     private parse;
+    /** Resolve a matching identity; deletion can retain legacy metadata without interpreting it. */
     private find;
     private seal;
     private open;
@@ -61,14 +62,18 @@ export declare class SecretsVaultService {
      * Prepared records contain envelopes and stay private to the host, never a public read model.
      * @example const record = await vault.prepare(input); await repo.put({ record, expectedRevision: input.expectedRevision }); // inside the host transaction
      */
-    prepare(input: VaultPutInput, _options?: VaultOptions): Promise<VaultRecord>;
+    prepare(input: VaultPutInput, _options?: VaultOptions): Promise<VaultPutRecord>;
     /** Resolve the target identity and apply the service-level CAS precheck. */
     private findForPut;
     private parsePutMeta;
     /** Omitted payload keeps the existing envelope and hints without opening or sealing. */
     private putEnvelope;
-    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership. */
-    get(input: VaultIdentity, _options?: VaultOptions): Promise<{
+    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership.
+     * `provider`, when given, must match the row's group before its envelope is opened (a stale
+     * selection never decrypts another group's secret). */
+    get(input: VaultIdentity, { provider }?: {
+        provider?: string;
+    }): Promise<{
         summary: VaultSummary;
         payload: VaultMeta | null;
     } | null>;
@@ -103,7 +108,8 @@ export declare class SecretsVaultService {
     private copyRow;
     /** Guarded read of the source row, then a CAS write of the resealed target row. */
     private transferRow;
-    /** Overwrite keeps the target's default, revision chain and creation time. */
+    /** Overwrite keeps the target's default, revision chain and creation time. A new copy leaves
+     * placement unspecified, so the repo's first-row rule applies (never the source's default flag). */
     private writeCopy;
     /** Human-managed scoped inventory. No envelope or plaintext is opened or returned. */
     list(input: VaultQuery, _options?: VaultOptions): Promise<VaultSummary[]>;
@@ -116,7 +122,9 @@ export declare class SecretsVaultService {
     rotate(input: VaultIdentity & {
         expectedRevision: number;
     }, _options?: VaultOptions): Promise<VaultSummary>;
-    /** Idempotent for missing rows; existing rows require matching context and revision. */
+    /** Idempotent for missing rows; existing rows require matching context and revision.
+     * Deletion needs no metadata interpretation, so unupgraded legacy rows remain removable.
+     */
     delete(input: VaultIdentity & {
         expectedRevision: number;
     }, _options?: VaultOptions): Promise<boolean>;