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

package/dist/fs/directory-workspace.js

@@ -85,7 +85,9 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
         const oldHome = legacy.state === "ok" ? legacy.value?.home : path.join(homeDir, userConfig.legacyDefaultFolder ?? defaultFolder);
         if (typeof oldHome !== "string")
             throw new Error("Legacy directory setting has an invalid home.");
-        return [...new Set([oldHome, ...config.legacyHomes({}), home()])].map((root) => createDirectoryRegistry({ file: fileAt(path.join(root, registryName)), canonicalPath }));
+        // Legacy settings use the same home shorthand contract; current overrides must not redirect the import.
+        const expandedHome = resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: oldHome }, { cwd, ...directoryOptions });
+        return [...new Set([expandedHome, ...config.legacyHomes({}), home()])].map((root) => createDirectoryRegistry({ file: fileAt(path.join(root, registryName)), canonicalPath }));
     };
     const importOldCatalog = () => {
         const current = atHome();

package/dist/fs/guarded-reader.d.ts

@@ -1,60 +1,32 @@
 import nodeFs from "node:fs";
-/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
-export declare class FsFilePathError extends Error {
-    constructor({ message }: {
-        message: string;
-    });
-}
-export interface DenyRules {
-    segments: ReadonlySet<string>;
-    filenamePatterns: readonly RegExp[];
-}
-export interface GuardedReaderLimits {
-    maxFileBytes: number;
-    binarySniffBytes: number;
-    maxListedFiles: number;
-    maxWalkDepth: number;
-    maxWalkEntries: number;
-}
-export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream">;
+import { type DenyRules, type GuardedFileReader, type GuardedReaderLimits } from '@jini-ai/core/filesystem';
+export { FsFilePathError, type DenyRules, type GuardedFileReader, type GuardedReaderLimits } from '@jini-ai/core/filesystem';
+/** Optional capabilities needed only when descriptor reads are requested. */
+export type DescriptorCapabilities = Partial<Pick<typeof nodeFs, "fstatSync" | "constants">>;
+export type DescriptorReadPolicy = {
+    /** Require exact permission bits, e.g. 0o600; no subset/superset matching. */
+    exactMode?: number;
+    /** Reject growth beyond the descriptor's initial size even below the byte cap. */
+    rejectGrowth?: boolean;
+};
+/** Additive descriptor policy in the guarded reader's existing options object. */
+export type AddedReaderOptions = {
+    descriptorRead?: DescriptorReadPolicy;
+};
+export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream"> & DescriptorCapabilities;
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export declare function createNodeGuardedReaderFilesystem(_required: Record<string, never>): GuardedReaderFilesystem;
-export interface GuardedFileReader {
-    resolve(required: {
-        relativePath: string;
-    }): string;
-    read(required: {
-        relativePath: string;
-    }): {
-        content: string;
-        bytes: number;
-    };
-    readBytes(required: {
-        relativePath: string;
-        maxBytes: number;
-    }): Promise<Uint8Array>;
-    list(required: Record<string, never>, optional?: {
-        relativePath?: string;
-    }): {
-        files: string[];
-        truncated: boolean;
-    };
-    isDeniedFileName(required: {
-        fileName: string;
-    }): boolean;
-    isDeniedPathSegment(required: {
-        segmentName: string;
-    }): boolean;
-}
 /** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
  * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ * Opt-in descriptor reads fail closed without fstat/no-follow/nonblocking capabilities. No-follow
+ * protects the final component, not concurrent ancestor-directory replacement.
  */
 export declare function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }: {
     rootPath: string;
     denyRules: DenyRules;
     limits: GuardedReaderLimits;
     filesystem: GuardedReaderFilesystem;
-}, { excludedListingDirs }?: {
+}, { excludedListingDirs, descriptorRead }?: {
     excludedListingDirs?: ReadonlySet<string>;
-}): GuardedFileReader;
+} & AddedReaderOptions): GuardedFileReader;
 //# sourceMappingURL=guarded-reader.d.ts.map

package/dist/fs/guarded-reader.js

@@ -1,22 +1,21 @@
 import nodeFs from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-// A distinct refusal class lets tool adapters treat rejected paths/content as actionable input
-// problems instead of redacting them as an internal crash.
-/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
-export class FsFilePathError extends Error {
-    constructor({ message }) { super(message); this.name = "FsFilePathError"; }
-}
+import { FsFilePathError } from '@jini-ai/core/filesystem';
+export { FsFilePathError } from '@jini-ai/core/filesystem';
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export function createNodeGuardedReaderFilesystem(_required) { return nodeFs; }
 /** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
  * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ * Opt-in descriptor reads fail closed without fstat/no-follow/nonblocking capabilities. No-follow
+ * protects the final component, not concurrent ancestor-directory replacement.
  */
-export function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }, { excludedListingDirs = new Set(["node_modules", ".git", "dist"]) } = {}) {
+export function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }, { excludedListingDirs = new Set(["node_modules", ".git", "dist"]), descriptorRead } = {}) {
     if (!rootPath)
         throw new TypeError("rootPath is required");
     for (const value of Object.values(limits))
         if (!Number.isSafeInteger(value) || value <= 0)
             throw new TypeError("reader limits must be positive safe integers");
+    const descriptorFlags = descriptorRead === undefined ? undefined : descriptorOpenFlags({ filesystem: fs, policy: descriptorRead });
     const { existsSync, lstatSync, readdirSync, realpathSync, statSync } = fs;
     const MAX_FS_FILE_BYTES = limits.maxFileBytes, BINARY_SNIFF_BYTES = limits.binarySniffBytes;
     const MAX_LISTED_FILES = limits.maxListedFiles, MAX_WALK_DEPTH = limits.maxWalkDepth, MAX_WALK_ENTRIES = limits.maxWalkEntries;
@@ -250,9 +249,11 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     }
     // Read one byte past the cap so a file that grew after stat is refused rather than clipped.
     function readBoundedSync(target, relativePath) {
-        const fd = fs.openSync(target, "r");
+        const { fd, maxBytes } = descriptorFlags === undefined
+            ? { fd: fs.openSync(target, "r"), maxBytes: MAX_FS_FILE_BYTES }
+            : openValidatedDescriptor({ target, relativePath, maxBytes: MAX_FS_FILE_BYTES });
         try {
-            const bounded = Buffer.alloc(MAX_FS_FILE_BYTES + 1);
+            const bounded = Buffer.alloc(maxBytes + 1);
             let count = 0;
             while (count < bounded.length) {
                 const read = fs.readSync(fd, bounded, count, bounded.length - count, null);
@@ -260,14 +261,30 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
                     break;
                 count += read;
             }
-            if (count > MAX_FS_FILE_BYTES)
-                throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
+            if (count > maxBytes)
+                throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${maxBytes}-byte readable limit` });
             return bounded.subarray(0, count);
         }
         finally {
             fs.closeSync(fd);
         }
     }
+    /** Owns the descriptor until validated; every refusal closes it before propagating. */
+    function openValidatedDescriptor({ target, relativePath, maxBytes }) {
+        const fd = openNoFollow({ target, relativePath });
+        try {
+            const stat = fs.fstatSync(fd);
+            assertDescriptorStat({ stat, relativePath, maxBytes }, descriptorRead);
+            return { fd, maxBytes: descriptorRead?.rejectGrowth ? Math.min(maxBytes, stat.size) : maxBytes };
+        }
+        catch (error) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* Preserve the validation error. */ }
+            throw error;
+        }
+    }
     // A stat-only size check can be bypassed by a growing file: bound the stream independently and
     // reject rather than return a clipped image/video. Destroy the stream on success or failure.
     async function openFsFileForRead(required) {
@@ -283,10 +300,11 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         return readBoundedStream(target, { relativePath, maxBytes });
     }
     async function readBoundedStream(target, { relativePath, maxBytes }) {
-        const stream = fs.createReadStream(target, { highWaterMark: Math.min(64 * 1024, maxBytes + 1) });
+        const opened = createBoundedStream({ target, relativePath, maxBytes });
+        const { stream } = opened;
         try {
             // Own refusals pass through; any other stream failure becomes this reader's refusal class.
-            return await collectBoundedChunks(stream, { relativePath, maxBytes }).catch((error) => Promise.reject(error instanceof FsFilePathError
+            return await collectBoundedChunks(stream, { relativePath, maxBytes: opened.maxBytes }).catch((error) => Promise.reject(error instanceof FsFilePathError
                 ? error
                 : new FsFilePathError({ message: `path '${relativePath}' could not be read: ${errorText(error)}` })));
         }
@@ -294,6 +312,36 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             stream.destroy();
         }
     }
+    /** O_NOFOLLOW refusals (ELOOP) and other open failures carry absolute host paths; surface only
+     * the caller's relative path, like every other refusal from this reader. */
+    function openNoFollow({ target, relativePath }) {
+        try {
+            return fs.openSync(target, descriptorFlags);
+        }
+        catch {
+            throw new FsFilePathError({ message: `path '${relativePath}' is a symbolic link or could not be opened` });
+        }
+    }
+    /** Transfer ownership to the stream only after construction; it alone closes on end/error. */
+    function createBoundedStream({ target, relativePath, maxBytes }) {
+        const highWaterMark = Math.min(64 * 1024, maxBytes + 1);
+        if (descriptorFlags === undefined)
+            return { stream: fs.createReadStream(target, { highWaterMark }), maxBytes };
+        const opened = openValidatedDescriptor({ target, relativePath, maxBytes });
+        try {
+            return {
+                stream: fs.createReadStream(target, { fd: opened.fd, autoClose: true, highWaterMark: Math.min(highWaterMark, opened.maxBytes + 1) }),
+                maxBytes: opened.maxBytes,
+            };
+        }
+        catch (error) {
+            try {
+                fs.closeSync(opened.fd);
+            }
+            catch { /* Preserve the construction error. */ }
+            throw error;
+        }
+    }
     return {
         resolve: ({ relativePath }) => resolveFsFilePath({ rootPath, relativePath }),
         read: ({ relativePath }) => readFsFile({ rootPath, relativePath }),
@@ -303,6 +351,27 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         isDeniedPathSegment: ({ segmentName }) => isDeniedFsPathSegment(segmentName),
     };
 }
+/** Validate opt-in capability support without weakening legacy filesystem adapters. */
+function descriptorOpenFlags({ filesystem, policy }) {
+    if (!filesystem.fstatSync || !filesystem.constants)
+        throw new TypeError("descriptorRead requires fstatSync and filesystem constants");
+    const { O_RDONLY, O_NOFOLLOW, O_NONBLOCK } = filesystem.constants;
+    if (!O_NOFOLLOW || !O_NONBLOCK || !Number.isInteger(O_RDONLY))
+        throw new TypeError("descriptorRead requires supported O_RDONLY, O_NOFOLLOW and O_NONBLOCK flags");
+    if (policy.exactMode !== undefined && (!Number.isInteger(policy.exactMode) || policy.exactMode < 0 || policy.exactMode > 0o7777))
+        throw new TypeError("exactMode must contain only permission bits (0o0000 through 0o7777)");
+    return O_RDONLY | O_NOFOLLOW | O_NONBLOCK;
+}
+/** Both read paths validate the opened object, independent of earlier pathname metadata. */
+function assertDescriptorStat({ stat, relativePath, maxBytes }, { exactMode } = {}) {
+    if (!stat.isFile())
+        throw new FsFilePathError({ message: `path '${relativePath}' is not a regular file` });
+    if (!Number.isSafeInteger(stat.size) || stat.size < 0 || stat.size > maxBytes)
+        throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${maxBytes}-byte descriptor limit` });
+    // Include setuid/setgid/sticky: "exact" 0o600 must refuse a 0o4600 file.
+    if (exactMode !== undefined && (stat.mode & 0o7777) !== exactMode)
+        throw new FsFilePathError({ message: `file '${relativePath}' does not have exact mode ${exactMode.toString(8)}` });
+}
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }

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

@@ -0,0 +1,15 @@
+import { type ProviderRegistry } from "@jini-ai/core/provider-registry";
+import { type EmailSender, type EmailSenderContext, type EmailSourceSummary } from "./email-sender.js";
+/** Shares the existing keyed-registry admission rules; no plugin contribution category is added. */
+export type EmailSenderRegistry = ProviderRegistry<EmailSender>;
+/** Creates an isolated registry, throwing on invalid ids or duplicate built-in senders.
+ * @complexity O(s) registrations for s senders; keyed lookup remains O(1). */
+export declare function createEmailSenderRegistry(required: {
+    readonly senders: readonly EmailSender[];
+}, _optional?: Record<string, never>): EmailSenderRegistry;
+/** Lists configurable events across all registered senders, with each sender enforcing access.
+ * Refuses a sender claiming another sender's sources. @complexity One list call per sender. */
+export declare function listEmailSources(required: EmailSenderContext & {
+    readonly registry: EmailSenderRegistry;
+}, _optional?: Record<string, never>): Promise<readonly EmailSourceSummary[]>;
+//# sourceMappingURL=email-sender-registry.d.ts.map

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

@@ -0,0 +1,22 @@
+import { createProviderRegistry } from "@jini-ai/core/provider-registry";
+import { EmailSenderError } from "./email-sender.js";
+/** Creates an isolated registry, throwing on invalid ids or duplicate built-in senders.
+ * @complexity O(s) registrations for s senders; keyed lookup remains O(1). */
+export function createEmailSenderRegistry(required, _optional = {}) {
+    return createProviderRegistry({ contract: "email_sender" }, {
+        seed: required.senders.map(sender => ({ id: sender.id, label: sender.label, provider: sender })),
+    });
+}
+/** Lists configurable events across all registered senders, with each sender enforcing access.
+ * Refuses a sender claiming another sender's sources. @complexity One list call per sender. */
+export async function listEmailSources(required, _optional = {}) {
+    const sources = [];
+    for (const { id, provider } of required.registry.list({})) {
+        const listed = await provider.listSources({ workspaceId: required.workspaceId, principalId: required.principalId });
+        if (listed.some(source => source.senderId !== id))
+            throw new EmailSenderError({ code: "ownership" });
+        sources.push(...listed);
+    }
+    return sources;
+}
+//# sourceMappingURL=email-sender-registry.js.map

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

@@ -0,0 +1,109 @@
+/**
+ * MOVE: Event data and recipient authority belong to the originating feature, independently of
+ * delivery providers. Hosts bind authorization, templates and persistence; this surface sends nothing.
+ */
+import type { EmailAddress, MailerSendOptions } from "./types.js";
+/** Explicit caller scope, including for background jobs running as a host service principal. */
+export interface EmailSenderContext {
+    readonly workspaceId: string;
+    readonly principalId: string;
+}
+/** A concrete event source; the same event name may occur for several sources or senders. */
+export interface EmailSourceRef {
+    readonly senderId: string;
+    readonly sourceId: string;
+}
+export interface EmailSourceSummary extends EmailSourceRef {
+    readonly label: string;
+    readonly eventName: string;
+}
+/** Token is the exact placeholder name, without braces. Labels are presentation only. */
+export interface EmailSourceField {
+    readonly token: string;
+    readonly label: string;
+    readonly required: boolean;
+}
+/** Recipient ids are source-owned choices, never caller-supplied addresses or expressions. */
+export interface EmailRecipientChoice {
+    readonly id: string;
+    readonly label: string;
+}
+export interface EmailReadiness {
+    readonly ready: boolean;
+    readonly blockers: readonly string[];
+}
+/** Persisted by the sender's existing write owner, never by a template-side relationship. */
+export interface EmailBindingInput {
+    readonly bindingId: string;
+    readonly enabled: boolean;
+    readonly templateId: string;
+    readonly recipientId: string;
+    readonly replyTo: string;
+}
+export interface EmailBinding extends EmailBindingInput {
+    readonly activatedAt: string | null;
+}
+export interface EmailSourceDescription extends EmailSourceSummary {
+    readonly fields: readonly EmailSourceField[];
+    readonly permittedRecipients: readonly EmailRecipientChoice[];
+    readonly purpose: NonNullable<MailerSendOptions["purpose"]>;
+    readonly lane: NonNullable<MailerSendOptions["lane"]>;
+    readonly binding: EmailBinding | null;
+    readonly readiness: EmailReadiness;
+}
+/** Only allowlisted event values and recipients cross this boundary; no stored event row. */
+export interface ResolvedEmailEvent {
+    /** Authoritative ISO event time, compared with the binding's latest activation to prevent backfill. */
+    readonly occurredAt: string;
+    readonly values: Readonly<Record<string, string>>;
+    readonly recipients: readonly {
+        readonly id: string;
+        readonly address: EmailAddress;
+    }[];
+}
+export type EmailSourceRequest = EmailSenderContext & {
+    readonly sourceId: string;
+};
+/** Every operation must authorize its own scope. Resolution also verifies event/source ownership.
+ * No example-listing API: hosts may offer an authorized latest submission or a labeled sample. */
+export interface EmailSender {
+    readonly id: string;
+    readonly label: string;
+    listSources(required: EmailSenderContext, optional?: Record<string, never>): Promise<readonly EmailSourceSummary[]>;
+    describeSource(required: EmailSourceRequest, optional?: Record<string, never>): Promise<EmailSourceDescription>;
+    resolveEvent(required: EmailSourceRequest & {
+        readonly eventId: string;
+    }, optional?: Record<string, never>): Promise<ResolvedEmailEvent>;
+    configureEmail(required: EmailSourceRequest & {
+        readonly binding: EmailBindingInput;
+    }, optional?: Record<string, never>): Promise<EmailBinding>;
+}
+/** Describe must report all placeholders, including those absent from the template declarations.
+ * Render must use send-safe rendering, supplied values only, and refuse a changed version. */
+export interface EmailTemplatePort {
+    describe(required: EmailSenderContext & {
+        readonly templateId: string;
+    }, optional?: Record<string, never>): Promise<{
+        readonly version: string;
+        readonly fields: readonly string[];
+        readonly placeholders: readonly string[];
+    }>;
+    render(required: EmailSenderContext & {
+        readonly templateId: string;
+        readonly version: string;
+        readonly values: Readonly<Record<string, string>>;
+    }, optional?: Record<string, never>): Promise<{
+        readonly subject: string;
+        readonly html: string;
+        readonly text: string;
+        readonly missingFields: readonly string[];
+    }>;
+}
+/** Caller-safe failures never include event values, recipients or credentials. */
+export declare class EmailSenderError extends Error {
+    readonly code: "forbidden" | "not_found" | "ownership" | "configuration" | "not_ready" | "incompatible" | "missing_value";
+    constructor(required: {
+        readonly code: EmailSenderError["code"];
+    }, _optional?: Record<string, never>);
+}
+//# sourceMappingURL=email-sender.d.ts.map

package/dist/mail/email-sender.js

@@ -0,0 +1,10 @@
+/** Caller-safe failures never include event values, recipients or credentials. */
+export class EmailSenderError extends Error {
+    code;
+    constructor(required, _optional = {}) {
+        super(`Email sender: ${required.code}`);
+        this.code = required.code;
+        this.name = "EmailSenderError";
+    }
+}
+//# sourceMappingURL=email-sender.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