@jini-ai/platform 0.6.11 → 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/index.d.ts

@@ -36,8 +36,8 @@ export { createCommandInvocation, createPackageManagerInvocation } from "./comma
 export { omitEnvironmentKeys } from "./child-environment.js";
 export type { ResolveSystemProxyEnvOptions, SystemProxyCommandRunner } from "./proxy-env.js";
 export { mergeProxyAwareEnv, parseMacosScutilProxyOutput, parseWindowsInternetSettingsProxyOutput, resolveSystemProxyEnv, } from "./proxy-env.js";
-export type { ProcessSnapshot, ProcessStampContract, ProcessStampField, ProcessStampShape, SpawnProcessRequest, StampedProcessMatchCriteria, StopProcessesResult, } from "./process.js";
-export { collectProcessTreePids, createProcessStampArgs, isProcessAlive, listProcessSnapshots, matchesProcessStamp, matchesStampedProcess, readFlagValue, readProcessStamp, readProcessStampFromCommand, spawnBackgroundProcess, spawnLoggedProcess, stopProcesses, waitForProcessExit, } from "./process.js";
+export type { ProcessUsage, ProcessUsagePorts, ProcessUsageOptions, ProcessSnapshot, ProcessStampContract, ProcessStampField, ProcessStampShape, SpawnProcessRequest, StampedProcessMatchCriteria, StopProcessesResult, } from "./process.js";
+export { collectProcessTreePids, createProcessStampArgs, isProcessAlive, listProcessSnapshots, listProcessUsage, matchesProcessStamp, matchesStampedProcess, readFlagValue, readProcessStamp, readProcessStampFromCommand, spawnBackgroundProcess, spawnLoggedProcess, stopProcesses, waitForProcessExit, } from "./process.js";
 export type { AtomicCopyFileOptions, AtomicCopyFileResult, RemovePathBestEffortOptions, RemovePathBestEffortResult, } from "./fs.js";
 export { atomicCopyFile, pathContains, readLogTail, removePathBestEffort } from "./fs.js";
 export type { HttpWaitOptions } from "./http.js";

package/dist/index.js

@@ -34,7 +34,7 @@
 export { createCommandInvocation, createPackageManagerInvocation } from "./command.js";
 export { omitEnvironmentKeys } from "./child-environment.js";
 export { mergeProxyAwareEnv, parseMacosScutilProxyOutput, parseWindowsInternetSettingsProxyOutput, resolveSystemProxyEnv, } from "./proxy-env.js";
-export { collectProcessTreePids, createProcessStampArgs, isProcessAlive, listProcessSnapshots, matchesProcessStamp, matchesStampedProcess, readFlagValue, readProcessStamp, readProcessStampFromCommand, spawnBackgroundProcess, spawnLoggedProcess, stopProcesses, waitForProcessExit, } from "./process.js";
+export { collectProcessTreePids, createProcessStampArgs, isProcessAlive, listProcessSnapshots, listProcessUsage, matchesProcessStamp, matchesStampedProcess, readFlagValue, readProcessStamp, readProcessStampFromCommand, spawnBackgroundProcess, spawnLoggedProcess, stopProcesses, waitForProcessExit, } from "./process.js";
 export { atomicCopyFile, pathContains, readLogTail, removePathBestEffort } from "./fs.js";
 export { waitForHttpOk } from "./http.js";
 export { FETCH_TIMEOUT_MS, FetchTimeoutError, fetchWithTimeout } from "./fetch-with-timeout.js";

package/dist/mail/adapter-module.d.ts

@@ -15,6 +15,12 @@ export interface MailAdapterCreateContext {
 }
 /** Provider modules return the ordinary mail port; the shared contract names no vendor. */
 export interface MailAdapterModule {
+    /** Optional host-resolved account connection for domain reads only. The host validates the
+     * HTTPS origin and plugin ownership; this credential must never replace the sending key. */
+    readonly domainReadConnection?: {
+        readonly serverId: string;
+        readonly baseUrl: string;
+    };
     create(context: MailAdapterCreateContext): MailerPort;
 }
 //# sourceMappingURL=adapter-module.d.ts.map

package/dist/mail/delivery-wrapper.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-provider wrapper around the existing delivery policy. Test mode is read for every recipient;
+ * limiter and observation-warning state live for the lifetime of the wrapper factory.
+ * The purpose gate still wraps the whole mailer at composition; this policy sits inside it.
+ */
+import { type MailResendPolicy } from "./policy.js";
+import type { MailCapturePort, MailerPort, MailSendLedgerPort, MailSuppressionRepoPort } from "./ports.js";
+import type { MailProviderModule } from "./provider.js";
+import type { MailerSendOptions, MailerSendResult, MailTestModeSetting, OutboundEmail } from "./types.js";
+export interface MailPolicyWrapperDeps {
+    ledger: MailSendLedgerPort;
+    suppression: MailSuppressionRepoPort;
+    /** Fresh host settings read; a mode change applies to the next recipient. */
+    readTestMode: () => Promise<MailTestModeSetting>;
+    /** The host owns purpose/module-specific resend decisions. */
+    resendPolicy: (required: {
+        options: MailerSendOptions;
+    }) => MailResendPolicy;
+    observe?: (required: {
+        message: OutboundEmail;
+        options: MailerSendOptions;
+        providerId: string;
+        mode: MailTestModeSetting;
+        result: MailerSendResult;
+    }) => Promise<void>;
+}
+export interface MailPolicyWrapperOptions {
+    /** Capture without a sink refuses rather than sending. */
+    capture?: MailCapturePort;
+    /** Limiter clock in ms; defaults to Date.now. */
+    now?: () => number;
+    /** Fixed observation-failure diagnostic; logger faults cannot affect delivery. */
+    warn?: (line: string) => void;
+}
+export interface MailPolicyWrapperInput {
+    providerId: string;
+    provider: MailProviderModule;
+    mailer: MailerPort;
+}
+/**
+ * Build the wrapper applied to each resolved provider. Settings/policy failures propagate;
+ * observer and diagnostic failures preserve the exact policy result.
+ * @complexity One settings read plus policy round-trips per recipient; batches run sequentially.
+ */
+export declare function createMailPolicyWrapper(required: MailPolicyWrapperDeps, optional?: MailPolicyWrapperOptions): (required: MailPolicyWrapperInput, optional?: Record<string, never>) => MailerPort;
+//# sourceMappingURL=delivery-wrapper.d.ts.map

package/dist/mail/delivery-wrapper.js

@@ -0,0 +1,109 @@
+/**
+ * Per-provider wrapper around the existing delivery policy. Test mode is read for every recipient;
+ * limiter and observation-warning state live for the lifetime of the wrapper factory.
+ * The purpose gate still wraps the whole mailer at composition; this policy sits inside it.
+ */
+import { createMailDeliveryPolicy } from "./policy.js";
+import { createMailLaneLimiter } from "./rate-limit.js";
+const CAPTURE_UNAVAILABLE = { ok: false, retryable: false, errorCode: "MAIL_TEST_CAPTURE_UNAVAILABLE", message: "mail test mode is set to capture, but no capture store is available; nothing was sent" };
+/** Maps settings to policy test mode; null means capture was requested without a sink. */
+function toTestMode(required) {
+    const { setting, capture } = required;
+    if (setting.mode === "redirect")
+        return { kind: "redirect", to: { email: setting.to } };
+    if (setting.mode === "capture")
+        return capture ? { kind: "capture", sink: capture } : null;
+    return undefined;
+}
+/** Preserve serialization order and null-provider approvals: these bytes are caller-owned. */
+function approvalChanged(required) {
+    const { message, options, providerId, mailer, setting } = required;
+    const approval = options.mailTestApproval;
+    const actual = { providerId, driver: mailer.capabilities({}).driver, from: message.from, mode: setting.mode, effectiveRecipient: setting.mode === "redirect" ? setting.to : message.to.email };
+    return !!approval && JSON.stringify({ ...actual, providerId: approval.providerId === null ? null : providerId }) !== JSON.stringify(approval);
+}
+/** Delivery has already happened: activity storage and diagnostics must never alter its result. */
+function createResultObserver(required, optional) {
+    let observationWarned = false;
+    return async function observeResult(event) {
+        try {
+            await required.observe?.(event);
+        }
+        catch {
+            if (observationWarned)
+                return;
+            observationWarned = true;
+            try {
+                (optional.warn ?? console.warn)("[mail] activity observation failed");
+            }
+            catch { /* Diagnostics cannot reject a send. */ }
+        }
+    };
+}
+/** One token bucket per provider id, shared across all mailers from this factory. */
+function createLimiterLookup(optional) {
+    const limiters = new Map();
+    return function limiterFor({ provider, providerId }) {
+        const limit = provider.capabilities.rateLimit;
+        if (!limit)
+            return undefined;
+        const existing = limiters.get(providerId);
+        if (existing)
+            return existing;
+        const created = createMailLaneLimiter({ limit }, optional.now ? { now: optional.now } : {});
+        limiters.set(providerId, created);
+        return created;
+    };
+}
+/** Convert the host's complete options to the existing mail port without changing delivery policy. */
+function sendToMailer(required) {
+    const { idempotencyKey, workspaceId, sourceContext, ...optional } = required.options;
+    return required.mailer.send({ message: required.message, idempotencyKey, workspaceId, sourceContext }, optional);
+}
+/** Read → approve → capture check → policy → observe. Rejections propagate before observation. */
+function createRecipientDelivery(required) {
+    const { providerId, mailer, deps, optional, limiterFor, observeResult } = required;
+    return async function deliverOne({ message, options }) {
+        const setting = await deps.readTestMode();
+        if (approvalChanged({ message, options, providerId, mailer, setting })) {
+            return { ok: false, retryable: false, errorCode: "MAIL_TEST_APPROVAL_CHANGED", message: "Mail configuration changed. Prepare a new approval; nothing was sent." };
+        }
+        const testMode = toTestMode({ setting, ...(optional.capture ? { capture: optional.capture } : {}) });
+        if (testMode === null)
+            return CAPTURE_UNAVAILABLE;
+        const limiter = limiterFor(required);
+        const policy = createMailDeliveryPolicy({ providerId, ledger: deps.ledger, suppression: deps.suppression, supportsAttachments: mailer.capabilities({}).supportsAttachments }, { ...(limiter ? { limiter } : {}), ...(testMode ? { testMode } : {}), resendPolicy: () => deps.resendPolicy({ options }) });
+        const result = await policy.deliver({ message, options, send: (call) => sendToMailer({ message: call.message, options, mailer }) });
+        await observeResult({ message, options, providerId, mode: setting, result });
+        return result;
+    };
+}
+/** Build a provider mailer; batches retain ordered, per-recipient policy results and indexed keys. */
+function wrapProviderMailer(required) {
+    const deliverOne = createRecipientDelivery(required);
+    return {
+        capabilities: () => required.mailer.capabilities({}),
+        send: ({ message, ...delivery }, optional = {}) => deliverOne({ message, options: { ...delivery, ...optional } }),
+        async sendBatch({ messages, ...delivery }, optional = {}) {
+            const options = { ...delivery, ...optional };
+            // Per-recipient ledger rows need per-recipient dispatch. A shared key makes messages 2..n
+            // look like retries of 1. Await each recipient so partial results and effects stay ordered.
+            const results = [];
+            for (const [index, message] of messages.entries())
+                results.push(await deliverOne({ message, options: { ...options, idempotencyKey: `${options.idempotencyKey}:${index}` } }));
+            return results;
+        },
+    };
+}
+/**
+ * Build the wrapper applied to each resolved provider. Settings/policy failures propagate;
+ * observer and diagnostic failures preserve the exact policy result.
+ * @complexity One settings read plus policy round-trips per recipient; batches run sequentially.
+ */
+export function createMailPolicyWrapper(required, optional = {}) {
+    const state = { deps: required, optional, limiterFor: createLimiterLookup(optional), observeResult: createResultObserver(required, optional) };
+    return function wrap(input, _optional = {}) {
+        return wrapProviderMailer({ ...input, ...state });
+    };
+}
+//# sourceMappingURL=delivery-wrapper.js.map

package/dist/mail/domain-read.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderResult } from "@jini-ai/core/provider-registry";
+import type { MailAdapterCredential } from "./adapter-module.js";
+import type { MailProviderCallContext } from "./provider.js";
+/** The active provider's plugin can supply a separate, read-capable account credential. */
+export type MailDomainReadCredentialPort = (required: {
+    id: string;
+}, options?: Record<string, never>) => Promise<MailAdapterCredential | null>;
+/** Only permission refusals justify asking for a more capable account connection. */
+export declare function isDomainReadPermissionRefused(required: {
+    result: ProviderResult<unknown>;
+}, _options?: Record<string, never>): boolean;
+/** Read with the sending key first, then the plugin's account key on a permission refusal.
+ * The replacement context is read-only and never reaches the sending mailer.
+ * @complexity At most two provider reads and one account-credential lookup. */
+export declare function readMailDomain<T>(required: {
+    ctx: MailProviderCallContext;
+    providerId: string;
+    read: (ctx: MailProviderCallContext) => Promise<ProviderResult<T>>;
+    resolveDomainReadCredential?: MailDomainReadCredentialPort;
+}, _options?: Record<string, never>): Promise<ProviderResult<T>>;
+//# sourceMappingURL=domain-read.d.ts.map

package/dist/mail/domain-read.js

@@ -0,0 +1,17 @@
+/** Only permission refusals justify asking for a more capable account connection. */
+export function isDomainReadPermissionRefused(required, _options = {}) {
+    const { result } = required;
+    return result.status === "rejected" && result.error.code === "forbidden";
+}
+/** Read with the sending key first, then the plugin's account key on a permission refusal.
+ * The replacement context is read-only and never reaches the sending mailer.
+ * @complexity At most two provider reads and one account-credential lookup. */
+export async function readMailDomain(required, _options = {}) {
+    const { ctx, providerId, read, resolveDomainReadCredential } = required;
+    const result = await read(ctx);
+    if (!isDomainReadPermissionRefused({ result }) || !resolveDomainReadCredential)
+        return result;
+    const credential = await resolveDomainReadCredential({ id: providerId }).catch(() => null);
+    return credential ? read({ ...ctx, credential }) : result;
+}
+//# sourceMappingURL=domain-read.js.map

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