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

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/sender-domain-verification.d.ts

@@ -0,0 +1,40 @@
+import type { MailAdapterCredential } from "./adapter-module.js";
+import type { MailProviderModule } from "./provider.js";
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { SenderDomainVerificationPort } from "./engine-contracts.js";
+import { type MailDomainReadCredentialPort } from "./domain-read.js";
+/**
+ * @file The sender domain's state at the active transactional provider (its own `domainStatus`),
+ * for callers that need the provider verdict. Kept apart from the DNS
+ * check on purpose: a provider can report `pending` after every record resolves, and DNS can match
+ * while the provider was never asked. Each reason the provider cannot be asked is named apart, so
+ * "DNS verification unavailable for this provider" is a state of its own, not a failure.
+ */
+export interface SenderDomainVerificationDeps {
+    workspaceId: string;
+    /** The host's guarded outbound-HTTP seam, handed through to the provider. */
+    httpClient: HttpClientPort;
+    /** The installed providers, read fresh (host catalog). */
+    findProvider: (required: {
+        id: string;
+    }) => Promise<MailProviderModule | undefined>;
+    /** The provider's saved key, or `null` when none is saved (host credential resolver). */
+    resolveCredential: (required: {
+        id: string;
+    }) => Promise<MailAdapterCredential | null>;
+    resolveDomainReadCredential?: MailDomainReadCredentialPort;
+    /** The configured transactional lane. */
+    readProviderId: () => Promise<string | null>;
+    /** The configured sender address. */
+    readSenderEmail: () => Promise<string | undefined>;
+}
+/**
+ * Build the never-throwing provider-verdict port. Lookup failures become explicit verdicts;
+ * the deadline covers the whole check and clears its timer without cancelling provider work.
+ * @complexity Per call: two settings reads, one catalog load, at most two key lookups and two provider calls; O(1) space.
+ * @example createSenderDomainVerification(deps)()
+ */
+export declare function createSenderDomainVerification(required: SenderDomainVerificationDeps, options?: {
+    timeoutMs?: number;
+}): SenderDomainVerificationPort;
+//# sourceMappingURL=sender-domain-verification.d.ts.map

package/dist/mail/sender-domain-verification.js

@@ -0,0 +1,71 @@
+import { credentialSecrets, safeMailProviderText } from "./provider-error.js";
+import { isDomainReadPermissionRefused, readMailDomain } from "./domain-read.js";
+/** The configured sender's domain, lower-cased; undefined when unset or unreadable.
+ * @complexity O(n) time and space in the sender address length; one settings read. */
+async function senderDomain(deps) {
+    const email = await deps.readSenderEmail().catch(() => undefined);
+    return email?.split("@")[1]?.trim().toLowerCase() || undefined;
+}
+/** Read domain status, trying the plugin's account on permission refusal; failures stay `unknown`.
+ * @complexity At most two provider reads and two key lookups; diagnostic output is capped at 1000 characters. */
+async function askProvider(required) {
+    const { deps, provider, providerId, domain } = required;
+    const credential = await deps.resolveCredential({ id: providerId }).catch(() => null);
+    if (!credential)
+        return { state: "unknown", domain, providerId, reason: "the provider's key is not saved" };
+    // Same call context `resolve-mailer.ts` builds for a provider call: this workspace, live, its key.
+    const ctx = { workspaceId: deps.workspaceId, mode: "live", credential, httpClient: deps.httpClient };
+    const result = await readMailDomain({ ctx, providerId, read: context => provider.domainStatus(context, { domain }), ...(deps.resolveDomainReadCredential ? { resolveDomainReadCredential: deps.resolveDomainReadCredential } : {}) }).catch(() => null);
+    if (result?.status === "ok")
+        return { state: result.value.state, domain, providerId };
+    return { state: "unknown", domain, providerId, reason: providerReadFailureReason({ result, credential }) };
+}
+/** A refusal both keys hit is named plainly; any other provider answer keeps its code+message,
+ * secret-redacted (the sending key's exact values plus Jini's patterns) and capped.
+ * @complexity O(n) diagnostic text plus credential values; output is capped at 1000 characters.
+ */
+function providerReadFailureReason(required) {
+    const { result, credential } = required;
+    if (!result)
+        return "the provider did not answer the domain check";
+    if (isDomainReadPermissionRefused({ result }))
+        return "the sending key can't check domains, and no connected account could check it either";
+    return safeMailProviderText({ text: `${result.error.code}: ${result.error.message}` }, { secrets: credentialSecrets({ credential }) });
+}
+/** Resolve the configured sender against its provider, independently of DNS answers.
+ * Settings start together; catalog and credential reads follow in their original await order.
+ * @complexity Two settings reads, one catalog lookup and at most two provider reads; O(1) space.
+ */
+async function checkSenderDomain(deps) {
+    const [providerId, domain] = await Promise.all([deps.readProviderId().catch(() => null), senderDomain(deps)]);
+    if (!domain)
+        return { state: "no_sender", providerId };
+    const provider = providerId === null ? undefined : await deps.findProvider({ id: providerId }).catch(() => undefined);
+    if (!provider)
+        return { state: "no_provider", domain, providerId };
+    const id = providerId;
+    if (!provider.domainStatus)
+        return { state: "unsupported", domain, providerId: id };
+    return askProvider({ deps, provider, providerId: id, domain });
+}
+/**
+ * Build the never-throwing provider-verdict port. Lookup failures become explicit verdicts;
+ * the deadline covers the whole check and clears its timer without cancelling provider work.
+ * @complexity Per call: two settings reads, one catalog load, at most two key lookups and two provider calls; O(1) space.
+ * @example createSenderDomainVerification(deps)()
+ */
+export function createSenderDomainVerification(required, options = {}) {
+    return async () => {
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => resolve({ state: "unknown", providerId: null, reason: "provider_domain_check_timed_out" }), options.timeoutMs ?? 5_000);
+        });
+        try {
+            return await Promise.race([checkSenderDomain(required), timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+//# sourceMappingURL=sender-domain-verification.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/mail/types.d.ts

@@ -39,6 +39,8 @@ export interface MailerSendOptions {
      * distinguish them. Unmapped/absent lanes resolve to notification rather than opening the
      * interactive bypass; the caller-facing facade applies that fail-closed allowlist. */
     lane?: "interactive" | "notification";
+    /** Configuration facts approved by the caller, rechecked immediately before delivery. */
+    mailTestApproval?: MailTestApproval;
 }
 /** Serializable outcomes cross the adapter ABI; live thrown objects cannot be carried as results. */
 export type MailerSendResult = {
@@ -89,4 +91,21 @@ export type MailerSendRequired = MailerDelivery & {
 export type MailerBatchRequired = MailerDelivery & {
     messages: readonly OutboundEmail[];
 };
+/** Persisted test-mode shape; capture availability is decided separately by the delivery wrapper. */
+export type MailTestModeSetting = {
+    mode: "off";
+} | {
+    mode: "redirect";
+    to: string;
+} | {
+    mode: "capture";
+};
+/** Preserve field order when constructing/comparing approvals: approval bytes are caller-owned. */
+export interface MailTestApproval {
+    providerId: string | null;
+    driver: string;
+    from: OutboundEmail["from"];
+    mode: MailTestModeSetting["mode"];
+    effectiveRecipient: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/process.d.ts

@@ -7,11 +7,12 @@
  * Windows `Get-CimInstance`), walk a process tree, and stop a set of PIDs with
  * SIGTERM-then-SIGKILL escalation.
  *
- * Depends on the `command` module for invocation construction; keeps a private
- * `errorCode` copy so it owns no cross-module runtime surface.
+ * Uses `command` for invocation construction and `shell`'s direct buffered
+ * executor for bounded usage samples; keeps a private `errorCode` copy.
  */
 import { type ChildProcess } from "node:child_process";
 import { type CommandInvocationRequest } from "./command.js";
+import { execFileBuffered } from "./shell.js";
 export type ProcessStampShape = object;
 export type ProcessStampField<TStamp extends ProcessStampShape> = Extract<keyof TStamp, string>;
 export type ProcessStampContract<TStamp extends ProcessStampShape, TCriteria extends Partial<TStamp> = Partial<TStamp>> = {
@@ -32,6 +33,22 @@ export type ProcessSnapshot = {
     pid: number;
     ppid: number;
 };
+/** Display-only usage: RSS is bytes; CPU is cumulative seconds across all cores. */
+export type ProcessUsage = {
+    pid: number;
+    ppid: number;
+    rssBytes: number;
+    cpuSeconds: number;
+    /** Executable basename only; empty when the OS provides no name. */
+    name: string;
+};
+export type ProcessUsagePorts = {
+    platform?: NodeJS.Platform;
+    run?: typeof execFileBuffered;
+};
+export type ProcessUsageOptions = {
+    timeoutMs?: number;
+};
 export type StampedProcessMatchCriteria<TStamp extends ProcessStampShape> = Partial<TStamp>;
 export type StopProcessesResult = {
     alreadyStopped: boolean;
@@ -139,6 +156,14 @@ export declare function waitForProcessExit(pid: number | null | undefined, timeo
  * @returns The current process snapshots (empty on error).
  */
 export declare function listProcessSnapshots(): Promise<ProcessSnapshot[]>;
+/**
+ * Sample process RSS and cumulative CPU without reading command lines. Returns
+ * [] on command, timeout, buffer or JSON failure. RSS totals may count shared
+ * pages more than once; CPU percentages require deltas between samples.
+ * @param input - Optional host platform and bounded command-execution port.
+ * @param options - Execution timeout (default 5000ms); output is capped at 8MiB.
+ */
+export declare function listProcessUsage(input?: ProcessUsagePorts, options?: ProcessUsageOptions): Promise<ProcessUsage[]>;
 /**
  * Collect the transitive set of descendant PIDs (including the roots) from a
  * process snapshot list, returned sorted by numeric PID descending for deterministic ordering.