@jini-ai/platform 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -28,6 +28,57 @@
  *
  * The set of names exported here is intentionally identical to the pre-split
  * public surface; importers see no change.
+
+ * Archived provenance rationale:
+ * ## Design decision: `project-storage.ts` was split, not ported wholesale or dropped
+ *
+ * The task brief asked to verify the recon's "leans OD" flag on
+ * `project-storage.ts` firsthand and either drop it or extract a generic core
+ * with OD's project-specific parts as an adapter, "depending on what you
+ * actually find." Read in full: the `ProjectStorage` interface,
+ * `LocalProjectStorage`, and `S3ProjectStorage` classes carry no OD nouns in
+ * their own logic — they're a backend-agnostic blob CRUD port (read/write/
+ * list/delete/stat under a scoping key) plus a local-disk and an
+ * S3-compatible implementation, both traversal-guarded. The **only** OD
+ * coupling in the file is the bottom `resolveProjectStorage()` factory
+ * function, which reads `OD_PROJECT_STORAGE`/`OD_S3_BUCKET`/`OD_S3_REGION`/
+ * `OD_S3_PREFIX`/`OD_S3_ENDPOINT`/`OD_S3_ACCESS_KEY_ID`/
+ * `OD_S3_SECRET_ACCESS_KEY`/`OD_S3_SESSION_TOKEN` directly from `process.env`.
+ *
+ * **Extracted, not dropped:** the interface + both implementations, ported to
+ * `src/blob-storage.ts` as `BlobStorage`/`BlobFileMeta`/`LocalBlobStorage`/
+ * `S3BlobStorage`/`S3BlobStorageOptions`/`StorageError`, with every
+ * `projectId: string` parameter renamed to `namespace: string` — per
+ * extraction-plan.md's Task-4 Port-2 finding ("OD's 'project' is a product
+ * model; engine needs a generic workspace/session store interface") and §2.1's
+ * "Runs key on an opaque `contextRef`, never `projectId`" convention, "project"
+ * specifically is flagged elsewhere in this porting effort as OD's noun, not
+ * the engine's — `namespace` carries no domain meaning here beyond "a
+ * top-level grouping/scoping key," which is what the parameter actually is
+ * structurally (nothing in `LocalBlobStorage`/`S3BlobStorage`'s logic assumes
+ * it means a design project).
+ *
+ * **Dropped, not ported:** `resolveProjectStorage()`. This is OD adapter
+ * wiring — a specific env-var-naming convention and the choice to read
+ * `process.env` directly inside the engine layer — not generic engine
+ * behavior. It has no equivalent anywhere else in this porting session's
+ * established pattern (`createSqliteEventLog`, `LocalBlobStorage`,
+ * `S3BlobStorage` are all called with explicit constructor arguments; none of
+ * `@jini/*`'s existing adapters read `process.env` inside their own
+ * constructors). A Jini host application composes its own equivalent
+ * (`new LocalBlobStorage(root)` or `new S3BlobStorage({ bucket, region,
+ * credentials, ... })` called directly, with whatever env-var convention that
+ * host prefers) rather than inheriting OD's `OD_S3_*` names or its
+ * env-selection shape.
+ *
+ * Landed in `@jini/platform`, not `@jini/sqlite`: this is a filesystem/network
+ * blob-storage primitive with no SQL involvement, parallel to this package's
+ * existing `fs.ts` (path containment / atomic copy) and `http.ts` (readiness
+ * polling) roles — `@jini/sqlite` is reserved for the `EventLog` port adapter
+ * and `better-sqlite3`-specific helpers (`db-inspect.ts`,
+ * `backend-config.ts`), none of which this needs. `aws-sigv4.ts` lives
+ * alongside it in the same package since it's `S3BlobStorage`'s only
+ * dependency and has no other consumer yet.
  */
 export type { CommandInvocation, CommandInvocationRequest } from "./command.js";
 export { createCommandInvocation, createPackageManagerInvocation } from "./command.js";
@@ -46,7 +97,7 @@ export { wellKnownUserToolchainBins } from "./toolchain.js";
 export type { BufferedCommandResult } from "./shell.js";
 export { execCommandViaLoginShell, execFileBuffered } from "./shell.js";
 export type { AssetCache, AssetCacheOptions, AssetCacheResult } from "./asset-cache.js";
-export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createValidatingLookup, isCacheableExternalUrl, isPrivateAddress, } from "./asset-cache.js";
+export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createValidatingLookup, isCacheableExternalUrl, } from "./asset-cache.js";
 export { expandHomePrefix, resolveProjectRelativePath } from "./home-expansion.js";
 export type { SandboxEnvConfig, SandboxRuntimeConfig, SandboxRuntimeRoots } from "./sandbox-env.js";
 export { applySandboxRuntimeEnv, ensureSandboxRuntimeDirs, isSandboxImportedProjectRootAllowed, isSandboxModeEnabled, resolveSandboxRuntimeConfig, resolveSandboxRuntimeConfigFromEnv, sandboxAgentProfilesConfigPath, sandboxImportAllowedRoots, sandboxImportedProjectRootUnavailableReason, } from "./sandbox-env.js";
@@ -60,4 +111,13 @@ export type { SigV4Credentials, SignSigV4Input, SignSigV4Result } from "./aws-si
 export { encodeS3PathSegment, signSigV4 } from "./aws-sigv4.js";
 export type { BlobFileMeta, BlobStorage, S3BlobStorageOptions } from "./blob-storage.js";
 export { LocalBlobStorage, S3BlobStorage, StorageError } from "./blob-storage.js";
+export * as filesystem from "./fs/index.js";
+export * as guardedHttp from "./http/guarded/index.js";
+export * as mail from "./mail/index.js";
+export * as smtp from "./mail/smtp.js";
+export * as secrets from "./secrets/index.js";
+export * as credentialSets from "./secrets/credential-sets/index.js";
+export { isPrivateAddress } from "./net/address.js";
+export { defaultPlatformMessages } from "./messages.js";
+export type { PlatformMessages } from "./messages.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -28,6 +28,57 @@
  *
  * The set of names exported here is intentionally identical to the pre-split
  * public surface; importers see no change.
+
+ * Archived provenance rationale:
+ * ## Design decision: `project-storage.ts` was split, not ported wholesale or dropped
+ *
+ * The task brief asked to verify the recon's "leans OD" flag on
+ * `project-storage.ts` firsthand and either drop it or extract a generic core
+ * with OD's project-specific parts as an adapter, "depending on what you
+ * actually find." Read in full: the `ProjectStorage` interface,
+ * `LocalProjectStorage`, and `S3ProjectStorage` classes carry no OD nouns in
+ * their own logic — they're a backend-agnostic blob CRUD port (read/write/
+ * list/delete/stat under a scoping key) plus a local-disk and an
+ * S3-compatible implementation, both traversal-guarded. The **only** OD
+ * coupling in the file is the bottom `resolveProjectStorage()` factory
+ * function, which reads `OD_PROJECT_STORAGE`/`OD_S3_BUCKET`/`OD_S3_REGION`/
+ * `OD_S3_PREFIX`/`OD_S3_ENDPOINT`/`OD_S3_ACCESS_KEY_ID`/
+ * `OD_S3_SECRET_ACCESS_KEY`/`OD_S3_SESSION_TOKEN` directly from `process.env`.
+ *
+ * **Extracted, not dropped:** the interface + both implementations, ported to
+ * `src/blob-storage.ts` as `BlobStorage`/`BlobFileMeta`/`LocalBlobStorage`/
+ * `S3BlobStorage`/`S3BlobStorageOptions`/`StorageError`, with every
+ * `projectId: string` parameter renamed to `namespace: string` — per
+ * extraction-plan.md's Task-4 Port-2 finding ("OD's 'project' is a product
+ * model; engine needs a generic workspace/session store interface") and §2.1's
+ * "Runs key on an opaque `contextRef`, never `projectId`" convention, "project"
+ * specifically is flagged elsewhere in this porting effort as OD's noun, not
+ * the engine's — `namespace` carries no domain meaning here beyond "a
+ * top-level grouping/scoping key," which is what the parameter actually is
+ * structurally (nothing in `LocalBlobStorage`/`S3BlobStorage`'s logic assumes
+ * it means a design project).
+ *
+ * **Dropped, not ported:** `resolveProjectStorage()`. This is OD adapter
+ * wiring — a specific env-var-naming convention and the choice to read
+ * `process.env` directly inside the engine layer — not generic engine
+ * behavior. It has no equivalent anywhere else in this porting session's
+ * established pattern (`createSqliteEventLog`, `LocalBlobStorage`,
+ * `S3BlobStorage` are all called with explicit constructor arguments; none of
+ * `@jini/*`'s existing adapters read `process.env` inside their own
+ * constructors). A Jini host application composes its own equivalent
+ * (`new LocalBlobStorage(root)` or `new S3BlobStorage({ bucket, region,
+ * credentials, ... })` called directly, with whatever env-var convention that
+ * host prefers) rather than inheriting OD's `OD_S3_*` names or its
+ * env-selection shape.
+ *
+ * Landed in `@jini/platform`, not `@jini/sqlite`: this is a filesystem/network
+ * blob-storage primitive with no SQL involvement, parallel to this package's
+ * existing `fs.ts` (path containment / atomic copy) and `http.ts` (readiness
+ * polling) roles — `@jini/sqlite` is reserved for the `EventLog` port adapter
+ * and `better-sqlite3`-specific helpers (`db-inspect.ts`,
+ * `backend-config.ts`), none of which this needs. `aws-sigv4.ts` lives
+ * alongside it in the same package since it's `S3BlobStorage`'s only
+ * dependency and has no other consumer yet.
  */
 export { createCommandInvocation, createPackageManagerInvocation } from "./command.js";
 export { mergeProxyAwareEnv, parseMacosScutilProxyOutput, parseWindowsInternetSettingsProxyOutput, resolveSystemProxyEnv, } from "./proxy-env.js";
@@ -37,7 +88,7 @@ export { waitForHttpOk } from "./http.js";
 export { FETCH_TIMEOUT_MS, FetchTimeoutError, fetchWithTimeout } from "./fetch-with-timeout.js";
 export { wellKnownUserToolchainBins } from "./toolchain.js";
 export { execCommandViaLoginShell, execFileBuffered } from "./shell.js";
-export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createValidatingLookup, isCacheableExternalUrl, isPrivateAddress, } from "./asset-cache.js";
+export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createValidatingLookup, isCacheableExternalUrl, } from "./asset-cache.js";
 export { expandHomePrefix, resolveProjectRelativePath } from "./home-expansion.js";
 export { applySandboxRuntimeEnv, ensureSandboxRuntimeDirs, isSandboxImportedProjectRootAllowed, isSandboxModeEnabled, resolveSandboxRuntimeConfig, resolveSandboxRuntimeConfigFromEnv, sandboxAgentProfilesConfigPath, sandboxImportAllowedRoots, sandboxImportedProjectRootUnavailableReason, } from "./sandbox-env.js";
 export { resolveDaemonCliPath, resolveDaemonPluginPreviewsDir, resolveDaemonResourceDir, resolveDaemonResourceRoot, resolveDataDir, resolveProcessResourcesPath, } from "./resource-paths.js";
@@ -45,4 +96,13 @@ export { createTerminalService, ensureSpawnHelperExecutable, resolveShell, spawn
 export { MANAGED_DOWNLOAD_ERROR_CODES, ManagedDownloadError, downloadCopyAndClear, inspectManagedDownload, managedDownload, pruneManagedDownloads, removeManagedDownload, } from "./download.js";
 export { encodeS3PathSegment, signSigV4 } from "./aws-sigv4.js";
 export { LocalBlobStorage, S3BlobStorage, StorageError } from "./blob-storage.js";
+// Cohesive subpaths remain available as namespaced APIs without colliding with legacy names.
+export * as filesystem from "./fs/index.js";
+export * as guardedHttp from "./http/guarded/index.js";
+export * as mail from "./mail/index.js";
+export * as smtp from "./mail/smtp.js";
+export * as secrets from "./secrets/index.js";
+export * as credentialSets from "./secrets/credential-sets/index.js";
+export { isPrivateAddress } from "./net/address.js";
+export { defaultPlatformMessages } from "./messages.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,20 @@
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { MailerPort } from "./ports.js";
+export interface MailAdapterCredential {
+    readonly token: string;
+    readonly baseUrl?: string;
+    readonly username?: string;
+}
+export interface MailAdapterKit {
+    /** Provider requests must use the guarded outbound HTTP seam so its egress policy applies. */
+    readonly httpClient: HttpClientPort;
+}
+export interface MailAdapterCreateContext {
+    readonly credential: MailAdapterCredential;
+    readonly kit: MailAdapterKit;
+}
+/** Provider modules return the ordinary mail port; the shared contract names no vendor. */
+export interface MailAdapterModule {
+    create(context: MailAdapterCreateContext): MailerPort;
+}
+//# sourceMappingURL=adapter-module.d.ts.map

package/dist/mail/adapter-module.js

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

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

@@ -0,0 +1,7 @@
+import type { MailerPort } from "./ports.js";
+/** Reads adapter capabilities without sending a message. */
+/** The console driver only logs messages locally, so it must never count as real delivery. */
+export declare function isMailDeliveryAvailable({ mailer }: {
+    mailer: MailerPort;
+}): boolean;
+//# sourceMappingURL=delivery-availability.d.ts.map

package/dist/mail/delivery-availability.js

@@ -0,0 +1,6 @@
+/** Reads adapter capabilities without sending a message. */
+/** The console driver only logs messages locally, so it must never count as real delivery. */
+export function isMailDeliveryAvailable({ mailer }) {
+    return mailer.capabilities({}).driver !== "console";
+}
+//# sourceMappingURL=delivery-availability.js.map

package/dist/mail/index.d.ts

@@ -0,0 +1,7 @@
+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 { isMailDeliveryAvailable } from "./delivery-availability.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mail/index.js

@@ -0,0 +1,3 @@
+export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
+export { isMailDeliveryAvailable } from "./delivery-availability.js";
+//# sourceMappingURL=index.js.map

package/dist/mail/ports.d.ts

@@ -0,0 +1,43 @@
+import type { UUID } from "@jini-ai/core/primitives";
+import type { MailerCapabilities, MailerSendResult, MailerSendRequired, MailerBatchRequired, MailerOptional } from "./types.js";
+export type { MailerCapabilities, MailerSendOptions, MailerSendResult, OutboundEmail } from "./types.js";
+export interface MailerPort {
+    capabilities(_required: Record<string, never>): MailerCapabilities;
+    send(required: MailerSendRequired, optional?: MailerOptional): Promise<MailerSendResult>;
+    sendBatch(required: MailerBatchRequired, optional?: MailerOptional): Promise<readonly MailerSendResult[]>;
+}
+export type ConsoleMailerAdapter = MailerPort;
+export type InMemoryMailerAdapter = MailerPort;
+export interface MailSuppressionRepoPort {
+    isSuppressed(required: {
+        workspaceId: UUID;
+        normalizedAddress: string;
+        scope: "global" | {
+            module: string;
+        };
+    }): Promise<boolean>;
+    suppress(required: {
+        workspaceId: UUID;
+        normalizedAddress: string;
+        scope: "global" | {
+            module: string;
+        };
+        reason: "bounced" | "complained" | "manual";
+    }): Promise<void>;
+}
+export interface MailSendDedupRepoPort {
+    wasSent(required: {
+        workspaceId: UUID;
+        idempotencyKey: string;
+    }): Promise<boolean>;
+    markSent(required: {
+        workspaceId: UUID;
+        idempotencyKey: string;
+    }): Promise<void>;
+}
+export interface DeliveryReadinessPolicy {
+    isReady(required: {
+        capabilityName: string;
+    }): boolean;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/mail/ports.js

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

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

@@ -0,0 +1,18 @@
+/** Unknown and absent lanes require a durable notification path in production.
+ * Local mode and explicit interactive sends proceed without that gate.
+ */
+import type { MailerPort, DeliveryReadinessPolicy } from "./ports.js";
+type RuntimeMode = "production" | "local";
+export interface WrapMailerWithPurposeGateOptions {
+    inner: MailerPort;
+    mode: RuntimeMode;
+    readiness: DeliveryReadinessPolicy;
+}
+/** Validates the mode at wrap time and gates notification sends/batches before delivery.
+ * Unknown modes throw TypeError; only explicit local mode bypasses durable readiness.
+ * @complexity O(1) policy work per send/batch, before delegating delivery.
+ * @example wrapMailerWithPurposeGate({ inner, mode: "production", readiness })
+ */
+export declare function wrapMailerWithPurposeGate(options: WrapMailerWithPurposeGateOptions): MailerPort;
+export {};
+//# sourceMappingURL=purpose-scoped-mailer.d.ts.map

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

@@ -0,0 +1,50 @@
+/** Unknown and absent lanes require a durable notification path in production.
+ * Local mode and explicit interactive sends proceed without that gate.
+ */
+// Allowlist the one interactive value: undefined, unknown values and type-bypassing casts
+// belong to the restrictive notification lane, so a new lane cannot accidentally bypass readiness.
+function resolveLane(options) {
+    return options.lane === "interactive" ? "interactive" : "notification";
+}
+function refusalError(capabilityName) {
+    return new Error(`MAILER_SEND_REFUSED_NO_DURABLE_PATH: notification-lane mailer send refused for capability "${capabilityName}" — no durable outbox path registered`);
+}
+// Decorate the existing port rather than inventing a second delivery contract. The caller resolves
+// mode once at composition; never re-read the environment per send and change policy mid-process.
+/** Validates the mode at wrap time and gates notification sends/batches before delivery.
+ * Unknown modes throw TypeError; only explicit local mode bypasses durable readiness.
+ * @complexity O(1) policy work per send/batch, before delegating delivery.
+ * @example wrapMailerWithPurposeGate({ inner, mode: "production", readiness })
+ */
+export function wrapMailerWithPurposeGate(options) {
+    const { inner, mode, readiness } = options;
+    // Validate once at composition: typos must never silently disable durable delivery.
+    if (mode !== "production" && mode !== "local") {
+        throw new TypeError('mailer mode must be "production" or "local"');
+    }
+    function checkGate(sendOptions) {
+        if (mode === "local")
+            return; // Local mode never refuses delivery.
+        const lane = resolveLane(sendOptions);
+        if (lane !== "notification")
+            return;
+        const capabilityName = sendOptions.sourceContext?.module ?? "unknown";
+        if (!readiness.isReady({ capabilityName })) {
+            throw refusalError(capabilityName);
+        }
+    }
+    return {
+        capabilities: (required) => inner.capabilities(required),
+        async send({ message, ...required }, optional = {}) {
+            const sendOptions = { ...required, ...optional };
+            checkGate(sendOptions);
+            return inner.send({ message, ...required }, optional);
+        },
+        async sendBatch({ messages, ...required }, optional = {}) {
+            const sendOptions = { ...required, ...optional };
+            checkGate(sendOptions);
+            return inner.sendBatch({ messages, ...required }, optional);
+        },
+    };
+}
+//# sourceMappingURL=purpose-scoped-mailer.js.map

package/dist/mail/smtp.d.ts

@@ -0,0 +1,79 @@
+/** SMTP adapter over an injected transport and clock; no SMTP vendor is loaded by core. */
+import { type Clock as ClockPort } from "@jini-ai/core/primitives";
+import type { MailerPort } from "./ports.js";
+import type { MailerCapabilities, MailerSendResult, MailerSendRequired, MailerBatchRequired, MailerOptional } from "./types.js";
+export interface SmtpTransport {
+    sendMail(required: {
+        mail: SmtpMailPayload;
+    }): Promise<{
+        messageId: string;
+    }>;
+}
+export interface SmtpMailPayload {
+    from: {
+        name?: string;
+        address: string;
+    };
+    to: {
+        name?: string;
+        address: string;
+    };
+    replyTo?: {
+        name?: string;
+        address: string;
+    };
+    subject: string;
+    html?: string;
+    text?: string;
+    headers?: Readonly<Record<string, string>>;
+    attachments?: {
+        filename: string;
+        content: string;
+        encoding: "base64";
+        contentType: string;
+    }[];
+}
+export declare class SmtpMailerAdapter implements MailerPort {
+    private readonly clock;
+    private readonly transport;
+    constructor({ transport, clock }: {
+        transport: SmtpTransport;
+        clock: ClockPort;
+    });
+    capabilities(_required: Record<string, never>): MailerCapabilities;
+    send({ message }: MailerSendRequired, _optional?: MailerOptional): Promise<MailerSendResult>;
+    sendBatch({ messages, ...required }: MailerBatchRequired, optional?: MailerOptional): Promise<readonly MailerSendResult[]>;
+}
+export interface CreateNodemailerSmtpTransportConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    };
+    nodemailer: NodemailerPort;
+}
+export declare function createNodemailerSmtpTransport(config: CreateNodemailerSmtpTransportConfig, { timeoutMs }?: {
+    timeoutMs?: number;
+}): SmtpTransport;
+/** A host can pass nodemailer's module structurally; this package never loads or requires it. */
+export interface NodemailerPort {
+    createTransport(required: {
+        host: string;
+        port: number;
+        secure: boolean;
+        auth: {
+            user: string;
+            pass: string;
+        };
+        connectionTimeout?: number;
+    }): NativeSmtpTransport;
+}
+/** Vendor-shaped adapter boundary; application mailers use SmtpTransport. */
+export interface NativeSmtpTransport {
+    sendMail(mail: SmtpMailPayload): Promise<{
+        messageId: string;
+    }>;
+}
+//# sourceMappingURL=smtp.d.ts.map

package/dist/mail/smtp.js

@@ -0,0 +1,102 @@
+/** SMTP adapter over an injected transport and clock; no SMTP vendor is loaded by core. */
+import { nowIso } from "@jini-ai/core/primitives";
+function toNodemailerAddress(address) {
+    // Object addresses delegate header-safe display-name quoting/encoding to the SMTP library.
+    return address.name ? { name: address.name, address: address.email } : { address: address.email };
+}
+const NON_RETRYABLE_SMTP_CODES = new Set(["EAUTH", "EENVELOPE", "EMESSAGE"]);
+function classifySmtpError(err) {
+    // Prefer the server's RFC 5321 reply: 4xx asks for retry, 5xx rejects the message as-is.
+    // Pre-response auth/envelope/content rejection is terminal; connection failures are transient.
+    // Unknown failures remain retryable to avoid silently dropping mail on an unfamiliar error shape.
+    const message = err instanceof Error ? err.message : String(err);
+    const responseCode = hasNumericField(err, "responseCode") ? err.responseCode : undefined;
+    if (responseCode !== undefined) {
+        const retryable = responseCode >= 400 && responseCode < 500;
+        return { ok: false, retryable, errorCode: `SMTP_${responseCode}`, message };
+    }
+    const code = hasStringField(err, "code") ? err.code : undefined;
+    if (code !== undefined) {
+        return { ok: false, retryable: !NON_RETRYABLE_SMTP_CODES.has(code), errorCode: code, message };
+    }
+    return { ok: false, retryable: true, errorCode: "SMTP_UNKNOWN_ERROR", message };
+}
+function hasNumericField(value, key) {
+    return typeof value === "object" && value !== null && key in value && typeof value[key] === "number";
+}
+function hasStringField(value, key) {
+    return typeof value === "object" && value !== null && key in value && typeof value[key] === "string";
+}
+export class SmtpMailerAdapter {
+    clock;
+    transport;
+    constructor({ transport, clock }) {
+        // Inject acceptance time so delivery outcomes can be checked deterministically without wall-clock I/O.
+        this.transport = transport;
+        this.clock = clock;
+    }
+    capabilities(_required) {
+        return {
+            driver: "smtp",
+            // SMTP has no dedup-key verb; a caller needs its own send ledger to prevent duplicate delivery.
+            supportsIdempotencyKey: false,
+            // Bounce/complaint feedback requires a separately configured return-path mailbox parser.
+            supportsWebhookFeedback: false,
+            maxBatchSize: 1,
+            supportsAttachments: true,
+        };
+    }
+    async send({ message }, _optional = {}) {
+        try {
+            const info = await this.transport.sendMail({ mail: {
+                    from: toNodemailerAddress(message.from),
+                    to: toNodemailerAddress(message.to),
+                    ...(message.replyTo ? { replyTo: toNodemailerAddress(message.replyTo) } : {}),
+                    subject: message.subject,
+                    ...(message.html !== undefined ? { html: message.html } : {}),
+                    ...(message.text !== undefined ? { text: message.text } : {}),
+                    ...(message.headers ? { headers: message.headers } : {}),
+                    ...(message.attachments && message.attachments.length > 0
+                        ? {
+                            attachments: message.attachments.map((attachment) => ({
+                                filename: attachment.filename,
+                                content: attachment.contentBase64,
+                                encoding: "base64",
+                                contentType: attachment.contentType,
+                            })),
+                        }
+                        : {}),
+                } });
+            return { ok: true, providerMessageId: info.messageId, acceptedAt: nowIso({ clock: this.clock }) };
+        }
+        catch (err) {
+            return classifySmtpError(err);
+        }
+    }
+    async sendBatch({ messages, ...required }, optional = {}) {
+        const results = [];
+        // SMTP has no native batch verb; sequential sends preserve one outcome per input message.
+        for (const message of messages) {
+            results.push(await this.send({ message, ...required }, optional));
+        }
+        return results;
+    }
+}
+export function createNodemailerSmtpTransport(config, { timeoutMs } = {}) {
+    // Delegate SMTP negotiation/authentication to the vendor rather than reimplementing the protocol.
+    const nodemailer = config.nodemailer;
+    const transporter = nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: config.auth,
+        ...(timeoutMs === undefined ? {} : { connectionTimeout: timeoutMs }),
+    });
+    return {
+        sendMail: async ({ mail }) => {
+            const info = await transporter.sendMail(mail);
+            return { messageId: info.messageId };
+        },
+    };
+}
+//# sourceMappingURL=smtp.js.map

package/dist/mail/types.d.ts

@@ -0,0 +1,83 @@
+import type { ISODateTime, UUID } from "@jini-ai/core/primitives";
+export interface OutboundEmail {
+    workspaceId: UUID;
+    to: EmailAddress;
+    from: EmailAddress;
+    replyTo?: EmailAddress;
+    subject: string;
+    /** At least one of html/text must be supplied; the transport does not render missing content. */
+    html?: string;
+    /** A plain-text alternative improves accessibility and deliverability. */
+    text?: string;
+    /** Allows caller-owned List-Unsubscribe and RFC 8058 one-click headers without provider coupling. */
+    headers?: Readonly<Record<string, string>>;
+    /** Additive/optional for existing consumers; content is base64 so no live stream/path crosses the ABI. */
+    attachments?: readonly EmailAttachment[];
+}
+export interface EmailAddress {
+    email: string;
+    name?: string;
+}
+export interface EmailAttachment {
+    filename: string;
+    contentType: string;
+    contentBase64: string;
+}
+export interface MailerSendOptions {
+    /** Redelivery must reuse this identity; generating a new key defeats outbox deduplication. */
+    idempotencyKey: string;
+    /** Scope suppression and send dedup to the same delivery boundary. */
+    workspaceId: UUID;
+    /** Preserve provenance so delivery feedback can be attributed to the originating campaign/module. */
+    sourceContext: {
+        module: string;
+        ref?: string;
+    };
+    timeoutMs?: number;
+    purpose?: "transactional" | "bulk" | `feature:${string}`;
+    /** Keep interaction separate from notification readiness: a shared transactional purpose cannot
+     * 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";
+}
+/** Serializable outcomes cross the adapter ABI; live thrown objects cannot be carried as results. */
+export type MailerSendResult = {
+    ok: true;
+    providerMessageId: string;
+    acceptedAt: ISODateTime;
+} | {
+    ok: false;
+    retryable: boolean;
+    errorCode: string;
+    message: string;
+};
+export interface MailerCapabilities {
+    driver: string;
+    supportsIdempotencyKey: boolean;
+    supportsWebhookFeedback: boolean;
+    /** A limit of one means sequential send fallback, not an optional batch method consumers branch on. */
+    maxBatchSize: number;
+    /** Required attachments must be refused when unsupported, never dropped while reporting success. */
+    supportsAttachments: boolean;
+}
+export interface MailerFeedbackEvent {
+    workspaceId: UUID;
+    providerMessageId: string;
+    sourceContext: {
+        module: string;
+        ref?: string;
+    };
+    kind: "delivered" | "bounced" | "complained";
+    hardBounce: boolean;
+    occurredAt: ISODateTime;
+}
+/** Required delivery identity/provenance belongs in the first argument of every send. */
+export type MailerDelivery = Pick<MailerSendOptions, "idempotencyKey" | "workspaceId" | "sourceContext">;
+export type MailerOptional = Omit<MailerSendOptions, keyof MailerDelivery>;
+export type MailerSendRequired = MailerDelivery & {
+    message: OutboundEmail;
+};
+export type MailerBatchRequired = MailerDelivery & {
+    messages: readonly OutboundEmail[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/mail/types.js

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

package/dist/messages.d.ts

@@ -0,0 +1,22 @@
+/** Neutral defaults for shared network, credential and filesystem boundaries.
+ * Hosts may replace the whole object; diagnostics retain structured context separately. */
+export interface PlatformMessages {
+    atomicModeInvalid(): string;
+    atomicTempPathInvalid(): string;
+    atomicTempNameInvalid(): string;
+    atomicSymlinkRefused(): string;
+    atomicPermissionsRefused(): string;
+    atomicJsonUnserializable(): string;
+    fileLockIntervalsInvalid(): string;
+    fileLockWriteNoProgress(): string;
+    egressRefused(): string;
+    rootKeySealedWarning(required: {
+        subject: string;
+    }): string;
+    fileLockTimeout(required: {
+        waitedMs: number;
+    }): string;
+    fileLockLost(): string;
+}
+export declare const defaultPlatformMessages: PlatformMessages;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.js

@@ -0,0 +1,15 @@
+export const defaultPlatformMessages = {
+    atomicModeInvalid: () => "atomic file mode must be permission bits between 0000 and 0777",
+    atomicTempPathInvalid: () => "atomic temp path must be a different same-directory file",
+    atomicTempNameInvalid: () => "atomic temp name must be one safe segment",
+    atomicSymlinkRefused: () => "atomic write refused a symbolic-link destination",
+    atomicPermissionsRefused: () => "atomic write refused non-owner-only permissions",
+    atomicJsonUnserializable: () => "atomic JSON data must be serializable",
+    fileLockIntervalsInvalid: () => "file lock intervals must be positive safe integers (timeout may be zero; stale may be Infinity)",
+    fileLockWriteNoProgress: () => "file lock ownership write made no progress",
+    egressRefused: () => "egress to the requested host was refused by the outbound network policy",
+    rootKeySealedWarning: ({ subject }) => `IMPORTANT: anything sealed while ${subject} was in place was sealed under key material derived from these same bytes, `,
+    fileLockTimeout: ({ waitedMs }) => `exclusive file lock timed out after ${Math.round(waitedMs)}ms`,
+    fileLockLost: () => "exclusive file lock lost ownership before the critical section finished",
+};
+//# sourceMappingURL=messages.js.map