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

package/README.md

@@ -37,6 +37,7 @@ need a `PtySpawn` implementation supplied by the caller — this package defines
   so profile-only `PATH` entries are visible).
 - **Filesystem** — `pathContains`, `atomicCopyFile`, `removePathBestEffort`, `readLogTail`.
 - **HTTP readiness** — `waitForHttpOk`.
+- **Deadline signals** — `createDeadlineSignal({ waitMs }, { signal, startedAt, now })` from `@jini-ai/platform/fetch-with-timeout`; subtracts elapsed milliseconds using the optional `now: () => number` clock (default `Date.now`) and combines the remaining budget with caller cancellation.
 - **Toolchain discovery** — `wellKnownUserToolchainBins` (npm/pnpm/bun/cargo/deno/go/pyenv,
   asdf/volta/mise/nvm/fnm shims).
 - **Proxy-aware env** — `resolveSystemProxyEnv`, `mergeProxyAwareEnv` (macOS `scutil` / Windows
@@ -221,6 +222,7 @@ vendor-shaped `NativeSmtpTransport` so the factory adapts the payload once. Poli
 
 | Subpath | API and required host ports/policy |
 | --- | --- |
+| `./mail` | `createMailAdapterContext({ credential, kit }, { now, settings })` supplies a live clock and fresh empty settings by default; modules validate opaque per-install settings. |
 | `@jini-ai/analytics` (separate package) | `ingestHit({ input, deps }, { hooks, hash })`, `normalizeIngestContext({ input, dailySalt }, { hash })`, `deriveDailySalt({ rootKeySeed, workspaceId, utcDate, saltContext })`. The host supplies sink/config, host resolution, HKDF context, and privacy bounds. `LocalBufferSink({}, { initialHits })` is process-local. |
 | `@jini-ai/cms/trash` (separate package) | `createTrashService({ repo, adapters, transaction, idGen, entityPolicy }, { retentionDays, ...optional })`, `createTrashSweep({ repo, adapters, transaction, entityPolicy })`, and `startTrashSweeper({ sweep, clock, scheduler, leaseOwner }, optional)`. The host owns authorization, transactions, retention, scheduling, and adapters; follow-up hooks are in argument two. |
 | `./fs` | `writeFileAtomic({ filePath, content, fs, tempName })`, `writeJsonFileAtomic({ filePath, data, fs, tempName })`, `upsertEnvLine({ source, key, value })`, `readEnvLine({ source, key })`, `resolvePathWithin({ root, segment })`. Atomic writes preserve existing modes and require filesystem/temp-name ports. |

package/dist/fetch-with-timeout.d.ts

@@ -89,6 +89,29 @@ export interface FetchWithTimeoutOptions {
     /** Host-supplied transport; defaults to the global fetch. */
     fetch?: typeof fetch;
 }
+/** Optional caller cancellation and elapsed-time accounting for a wait budget. */
+export interface DeadlineSignalOptions {
+    signal?: AbortSignal;
+    /** Start time in milliseconds, on the same clock as `now`. */
+    startedAt?: number;
+    /** Clock port in milliseconds; defaults to Date.now and is read only with startedAt. */
+    now?: () => number;
+}
+/**
+ * Creates one signal that aborts when the remaining wait budget expires or the caller cancels.
+ * Spent time is subtracted once; future start times cannot increase the original budget.
+ * @param input - Wait budget in milliseconds. Negative remaining budgets become zero.
+ * @param options - Optional caller signal, start time and clock port.
+ * @returns A native deadline signal preserving the first abort reason. Zero expires asynchronously,
+ * following AbortSignal.timeout(0); an already-aborted caller is reflected immediately.
+ * Creates a native timeout without mutating inputs or the caller's signal.
+ * @throws {RangeError} If the remaining delay is invalid for AbortSignal.timeout.
+ * @complexity O(1) time and space.
+ * @example createDeadlineSignal({ waitMs: 5_000 }, { signal, startedAt, now: Date.now })
+ */
+export declare function createDeadlineSignal({ waitMs }: {
+    waitMs: number;
+}, { signal, startedAt, now }?: DeadlineSignalOptions): AbortSignal;
 /** Opt-in byte and decoding guards; defaults remain unlimited and replacement-decoded. */
 export type TextReadOptions = {
     /** Nonnegative safe integer. Actual streamed bytes, independent of Content-Length. */

package/dist/fetch-with-timeout.js

@@ -87,6 +87,25 @@ export const FETCH_TIMEOUT_MS = {
      * legitimately still-generating request early. */
     GENERATE: 10 * 60_000,
 };
+/**
+ * Creates one signal that aborts when the remaining wait budget expires or the caller cancels.
+ * Spent time is subtracted once; future start times cannot increase the original budget.
+ * @param input - Wait budget in milliseconds. Negative remaining budgets become zero.
+ * @param options - Optional caller signal, start time and clock port.
+ * @returns A native deadline signal preserving the first abort reason. Zero expires asynchronously,
+ * following AbortSignal.timeout(0); an already-aborted caller is reflected immediately.
+ * Creates a native timeout without mutating inputs or the caller's signal.
+ * @throws {RangeError} If the remaining delay is invalid for AbortSignal.timeout.
+ * @complexity O(1) time and space.
+ * @example createDeadlineSignal({ waitMs: 5_000 }, { signal, startedAt, now: Date.now })
+ */
+export function createDeadlineSignal({ waitMs }, { signal, startedAt, now = Date.now } = {}) {
+    const elapsedMs = startedAt === undefined ? 0 : Math.max(0, now() - startedAt);
+    const deadline = AbortSignal.timeout(Math.max(0, waitMs - elapsedMs));
+    if (signal === undefined)
+        return deadline;
+    return AbortSignal.any([deadline, signal]);
+}
 export async function readFetchResponseText(input, { maxResponseBytes, strictUtf8 = false } = {}) {
     const details = "result" in input && input.result === "details";
     const options = details ? input : { ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }), strictUtf8 };

package/dist/index.d.ts

@@ -42,8 +42,8 @@ export type { AtomicCopyFileOptions, AtomicCopyFileResult, RemovePathBestEffortO
 export { atomicCopyFile, pathContains, readLogTail, removePathBestEffort } from "./fs.js";
 export type { HttpWaitOptions } from "./http.js";
 export { waitForHttpOk } from "./http.js";
-export type { FetchWithTimeoutOptions } from "./fetch-with-timeout.js";
-export { FETCH_TIMEOUT_MS, FetchTimeoutError, fetchWithTimeout } from "./fetch-with-timeout.js";
+export type { DeadlineSignalOptions, FetchWithTimeoutOptions } from "./fetch-with-timeout.js";
+export { FETCH_TIMEOUT_MS, FetchTimeoutError, createDeadlineSignal, fetchWithTimeout } from "./fetch-with-timeout.js";
 export type { WellKnownUserToolchainOptions } from "./toolchain.js";
 export { wellKnownUserToolchainBins } from "./toolchain.js";
 export type { BufferedCommandResult } from "./shell.js";

package/dist/index.js

@@ -37,7 +37,7 @@ export { mergeProxyAwareEnv, parseMacosScutilProxyOutput, parseWindowsInternetSe
 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";
+export { FETCH_TIMEOUT_MS, FetchTimeoutError, createDeadlineSignal, fetchWithTimeout } from "./fetch-with-timeout.js";
 export { wellKnownUserToolchainBins } from "./toolchain.js";
 export { execCommandViaLoginShell, execFileBuffered } from "./shell.js";
 export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createAssetCacheDispatcher, createValidatingLookup, isCacheableExternalUrl, } from "./asset-cache.js";

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

@@ -12,7 +12,25 @@ export interface MailAdapterKit {
 export interface MailAdapterCreateContext {
     readonly credential: MailAdapterCredential;
     readonly kit: MailAdapterKit;
+    /** Sample at the point of use. Hosts normalize this to the real clock when omitted. */
+    readonly now?: () => Date;
+    /** Per-install configuration; only the provider module owns its schema and validation. */
+    readonly settings?: unknown;
 }
+/**
+ * Normalize a host's module context without inspecting settings or replacing its guarded ports.
+ * The optional fields on {@link MailAdapterCreateContext} preserve legacy direct create calls;
+ * hosts use this boundary to supply both defaults before invoking a provider module.
+ * @param required Sending credential and guarded adapter kit, passed through unchanged.
+ * @param optional Clock and opaque per-install settings. Only undefined selects a default.
+ * @returns A context with a live clock and settings (a fresh empty object when omitted).
+ * @complexity O(1) time and space; does not sample the clock or perform I/O.
+ * @example provider.create(createMailAdapterContext({ credential, kit }, { now, settings }));
+ */
+export declare function createMailAdapterContext(required: {
+    credential: MailAdapterCredential;
+    kit: MailAdapterKit;
+}, { now, settings }?: Pick<MailAdapterCreateContext, "now" | "settings">): Required<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

package/dist/mail/adapter-module.js

@@ -1,2 +1,14 @@
-export {};
+/**
+ * Normalize a host's module context without inspecting settings or replacing its guarded ports.
+ * The optional fields on {@link MailAdapterCreateContext} preserve legacy direct create calls;
+ * hosts use this boundary to supply both defaults before invoking a provider module.
+ * @param required Sending credential and guarded adapter kit, passed through unchanged.
+ * @param optional Clock and opaque per-install settings. Only undefined selects a default.
+ * @returns A context with a live clock and settings (a fresh empty object when omitted).
+ * @complexity O(1) time and space; does not sample the clock or perform I/O.
+ * @example provider.create(createMailAdapterContext({ credential, kit }, { now, settings }));
+ */
+export function createMailAdapterContext(required, { now = () => new Date(), settings = {} } = {}) {
+    return { credential: required.credential, kit: required.kit, now, settings };
+}
 //# sourceMappingURL=adapter-module.js.map

package/dist/mail/index.d.ts

@@ -1,6 +1,7 @@
 export type * from "./types.js";
 export type * from "./ports.js";
 export type * from "./adapter-module.js";
+export { createMailAdapterContext } from "./adapter-module.js";
 export type * from "./engine-contracts.js";
 export { wrapMailerWithPurposeGate, isPurposeGateOpen } from "./purpose-scoped-mailer.js";
 export type { WrapMailerWithPurposeGateOptions, PurposeGateRequired } from "./purpose-scoped-mailer.js";

package/dist/mail/index.js

@@ -1,3 +1,4 @@
+export { createMailAdapterContext } from "./adapter-module.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";

package/dist/mail/provider.js

@@ -21,11 +21,14 @@ export function validateMailProvider({ provider }) {
     // A capability claim without the code behind it is how Resend once advertised feedback with no route.
     if (caps.feedback !== (provider.feedback !== undefined))
         return "capabilities.feedback must match the presence of a feedback parser";
-    const hasDomain = typeof provider.domainRequirements === "function" && typeof provider.domainStatus === "function";
+    const hasDomain = hasDomainVerification(provider);
     if (caps.domainVerification !== hasDomain)
         return "capabilities.domainVerification must match domainRequirements + domainStatus";
     return undefined;
 }
+function hasDomainVerification(provider) {
+    return typeof provider.domainRequirements === "function" && typeof provider.domainStatus === "function";
+}
 /** Mail registry over the shared keyed registry; built-ins throw on a bad registration, plugins are refused. */
 export function createMailProviderRegistry(_required = {}, optional = {}) {
     const seed = (optional.builtins ?? []).map((provider) => ({ id: provider.id, provider, label: provider.label }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/platform",
-  "version": "0.6.15-rc.1",
+  "version": "0.6.15-rc.2",
   "description": "Generic OS/platform primitives: process exec and lifecycle, filesystem containment, HTTP readiness polling, toolchain discovery, blob storage, AWS signing, and an SSRF-safe asset cache.",
   "license": "Apache-2.0",
   "repository": {
@@ -206,7 +206,7 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@jini-ai/core": "^0.6.15-rc.1"
+    "@jini-ai/core": "^0.6.15-rc.2"
   },
   "publishConfig": {
     "access": "public",