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

package/dist/mail/resolve-mailer.js

@@ -0,0 +1,348 @@
+/**
+ * Explicit lane selection, live credential rotation and cached provider status.
+ * Saved keys never select a provider. Local fallback uses the catalog's console provider;
+ * production refuses. Host ports retain trusted loading, credential copy and configuration DTOs.
+ * capabilities() is synchronous and reports console until transactional resolution settles;
+ * sends always await their own lane. Invalidation detaches obsolete work without cancelling it.
+ */
+import { ToolInputError } from "@jini-ai/core";
+import { readMailDomain } from "./domain-read.js";
+import { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+import { credentialSecrets, safeMailProviderText } from "./provider-error.js";
+import { computeMailStatus, initialMailProviderSetting } from "./provider.js";
+import { laneForPurpose } from "./policy.js";
+import { createSenderDomainVerification } from "./sender-domain-verification.js";
+const CONSOLE_CAPABILITIES = { driver: "console", supportsIdempotencyKey: false, supportsWebhookFeedback: false, maxBatchSize: 1, supportsAttachments: true };
+/** Metadata identifies the exact saved version without decryption. @complexity O(1). */
+function rowFingerprint(record) {
+    return record ? `${record.id}:${record.vaultRevision ?? ""}:${record.updatedAt}` : "absent";
+}
+/** Any failed recipient wins; only a wholly accepted, nonempty operation clears a send failure.
+ * Results and exceptions pass through unchanged. @complexity O(messages) time, O(1) space. */
+function observeFailures(required) {
+    const { mailer, providerId, record, accepted } = required;
+    const seen = (results) => {
+        const failure = results.find(result => !result.ok);
+        if (failure && !failure.ok) {
+            record({ providerId, source: "send", code: failure.errorCode, message: failure.message });
+            return;
+        }
+        if (results.length > 0)
+            accepted();
+    };
+    return {
+        capabilities: () => mailer.capabilities({}),
+        send: async (input, options) => { const result = await mailer.send(input, options); seen([result]); return result; },
+        sendBatch: async (input, options) => { const results = await mailer.sendBatch(input, options); seen(results); return results; },
+    };
+}
+/** Refusals report console so availability checks never mistake them for delivery. @complexity O(messages) for batches. */
+function refusingMailer(required) {
+    const result = { ok: false, retryable: false, errorCode: required.errorCode, message: required.message };
+    return { capabilities: () => CONSOLE_CAPABILITIES, send: async () => result, sendBatch: async ({ messages }) => messages.map(() => result) };
+}
+/** Diagnostic sinks cannot throw across the mail boundary; production warns once per reason. */
+function warnOnce({ state, key, message }) {
+    if (state.deps.mode !== "production" || state.warned.has(key))
+        return;
+    state.warned.add(key);
+    try {
+        state.warn(message);
+    }
+    catch { /* Diagnostics cannot reject a send. */ }
+}
+/** Never retain provider/body details. Repeated checks must not hide a failed send. */
+function recordError({ state, error }) {
+    const { providerId, source } = error;
+    if (source === "check" && state.lastError?.source === "send")
+        return;
+    state.lastError = { providerId, source, message: source === "send" ? "The provider did not confirm acceptance. Check provider configuration." : "The provider configuration check could not complete.", at: new Date(state.nowMs()).toISOString() };
+}
+/** First boot remains unconfigured even with saved keys; failed persistence is retried on a later read. */
+async function initialize(state) {
+    const setting = initialMailProviderSetting({});
+    await state.deps.providerSetting.write({ setting }).catch(() => warnOnce({ state, key: "initialization", message: "[mail] the mail provider setting could not be saved; retrying on the next send" }));
+    return setting;
+}
+/** Only initialization is single-flight: every call still reads the current selection first. */
+async function currentSetting(state) {
+    const stored = await state.deps.providerSetting.read({});
+    if (stored)
+        return stored;
+    state.initialization ??= initialize(state).finally(() => { state.initialization = undefined; });
+    return state.initialization;
+}
+/** Keyless providers never touch the credential metadata store. */
+async function fingerprintFor({ state, label }) {
+    if (label === undefined)
+        return "";
+    return rowFingerprint(await state.deps.credentials.readFact({ label }));
+}
+/** The host catalog guarantees the built-in console provider. Its mailer shares the policy wrapper. */
+async function consoleMailer({ state, catalog }) {
+    const provider = catalog.registry.get({ id: "console" }).provider;
+    const mailer = state.wrap({ providerId: "console", provider, mailer: state.deps.createProviderMailer({ provider, credential: { token: "" } }) });
+    state.resolved.set("console", { mailer, fingerprint: "" });
+    return mailer;
+}
+/** Local mode keeps working through console; production refuses and logs safe host copy once. */
+async function fallback(required) {
+    const { state } = required;
+    if (state.deps.mode !== "production")
+        return state.resolved.get("console")?.mailer ?? consoleMailer(required);
+    warnOnce({ state, key: required.errorCode + required.message, message: required.message });
+    return refusingMailer(required);
+}
+/** A missing key or failed decrypt uses the host's established caller-safe refusal wording. */
+async function credentialOrReason({ state, catalog, id, label }) {
+    try {
+        const credential = await state.deps.credentials.resolve({ catalog, id });
+        if (credential)
+            return { credential };
+    }
+    catch (err) {
+        return { reason: state.deps.credentialFailureReason({ label, err }) };
+    }
+    return { reason: state.deps.missingCredentialReason({ label }) };
+}
+/** A catalog label means a saved key is required; keyless providers receive an empty token. */
+function providerCredential({ state, catalog, id }) {
+    const label = catalog.credentialLabelFor({ id });
+    return label === undefined ? Promise.resolve({ credential: { token: "" } }) : credentialOrReason({ state, catalog, id, label });
+}
+/** Preserve provider selection refusals, including the catalog's trusted plugin-load diagnostics. */
+function unavailable(required) {
+    return fallback({ ...required, errorCode: "MAIL_PROVIDER_UNAVAILABLE", message: `[mail] the selected mail provider '${required.id}' ${required.detail}, so outbound mail is NOT being sent` });
+}
+/** A successful operation only clears a failure from the same provider. */
+function acceptProvider({ state, id }) {
+    if (state.lastError?.source === "send" && state.lastError.providerId === id)
+        state.lastError = undefined;
+}
+/** Construct only after metadata/key/metadata agree; a generation change prevents caching obsolete work.
+ * @complexity One catalog load, two metadata reads and one decrypt per attempt; races retry in order. */
+async function resolveProvider({ state, id, startedIn }) {
+    const catalog = await state.deps.loadCatalog({});
+    const entry = catalog.registry.get({ id });
+    if (!entry) {
+        const refusals = catalog.refusals.length > 0 ? ` (${catalog.refusals.join("; ")})` : "";
+        return unavailable({ state, catalog, id, detail: `is not installed${refusals}` });
+    }
+    // Fingerprint BEFORE reading the key: a rotation racing this read then re-resolves next send.
+    // An unreadable store leaves key lookup to report why; "unknown" re-resolves once it reads.
+    const label = catalog.credentialLabelFor({ id });
+    const fingerprint = await fingerprintFor({ state, label }).catch(() => "unknown");
+    const found = await providerCredential({ state, catalog, id });
+    if (!found.credential)
+        return unavailable({ state, catalog, id, detail: found.reason });
+    const credential = found.credential;
+    const latest = await fingerprintFor({ state, label }).catch(() => fingerprint);
+    if (latest !== fingerprint)
+        return resolveProvider({ state, id, startedIn: state.generation });
+    const observed = observeFailures({ mailer: state.deps.createProviderMailer({ provider: entry.provider, credential }), providerId: id,
+        record: error => recordError({ state, error }), accepted: () => acceptProvider({ state, id }) });
+    const mailer = state.wrap({ providerId: id, provider: entry.provider, mailer: observed });
+    if (startedIn === state.generation)
+        state.resolved.set(id, { mailer, fingerprint, ...(label === undefined ? {} : { label }) });
+    return mailer;
+}
+/** Boot and early sends share one resolution per provider. Old completions rejoin the current generation. */
+function resolveOnce({ state, id }) {
+    const existing = state.inFlight.get(id);
+    if (existing)
+        return existing;
+    const startedIn = state.generation;
+    const started = resolveProvider({ state, id, startedIn }).then(mailer => startedIn === state.generation ? mailer : resolveOnce({ state, id }))
+        .finally(() => { if (state.inFlight.get(id) === started)
+        state.inFlight.delete(id); });
+    state.inFlight.set(id, started);
+    return started;
+}
+/** Reuse unchanged rows; metadata faults keep a usable cached mailer. @complexity One metadata read per send. */
+async function currentMailer({ state, id }) {
+    const entry = state.resolved.get(id);
+    if (!entry)
+        return resolveOnce({ state, id });
+    if (entry.label === undefined)
+        return entry.mailer;
+    const fingerprint = await fingerprintFor({ state, label: entry.label }).catch(() => entry.fingerprint);
+    if (fingerprint === entry.fingerprint)
+        return entry.mailer;
+    if (state.resolved.get(id) === entry)
+        state.resolved.delete(id);
+    return resolveOnce({ state, id });
+}
+/** Fresh lane selection precedes every resolution and updates the synchronous transactional projection. */
+async function mailerForLane({ state, lane }) {
+    const id = (await currentSetting(state))[lane];
+    const mailer = id === null
+        ? await fallback({ state, catalog: await state.deps.loadCatalog({}), errorCode: "MAIL_UNCONFIGURED", message: state.deps.unconfiguredMessage({ lane }) })
+        : await currentMailer({ state, id });
+    if (lane === "transactional")
+        state.lastTransactional = mailer;
+    return mailer;
+}
+/** Settings/catalog faults become a refusal rather than throwing across the routing boundary. */
+function forLane(required) {
+    return mailerForLane(required).catch(() => refusingMailer({ errorCode: "MAIL_PROVIDER_UNAVAILABLE", message: "Mail provider selection failed; check configuration." }));
+}
+/** The public mailer preserves synchronous capability reporting and awaits the proper lane for sends. */
+function createRouter(state) {
+    return {
+        capabilities: () => {
+            if (state.lastTransactional === undefined)
+                void forLane({ state, lane: "transactional" });
+            return state.lastTransactional?.capabilities({}) ?? CONSOLE_CAPABILITIES;
+        },
+        send: async (input, options = {}) => (await forLane({ state, lane: laneForPurpose({ purpose: options.purpose }) })).send(input, options),
+        sendBatch: async (input, options = {}) => (await forLane({ state, lane: laneForPurpose({ purpose: options.purpose }) })).sendBatch(input, options),
+    };
+}
+/** Sender settings errors count as unset; parsing retains the original lowercase/trim behavior. */
+async function readSenderDomain(state) {
+    const email = await state.options.readSenderEmail?.().catch(() => undefined);
+    return email?.split("@")[1]?.trim().toLowerCase() || undefined;
+}
+/** Domain status shares selection/credentials with delivery, while keeping its own ordered reads. */
+function createDomainVerification({ state, resolveDomainReadCredential }) {
+    return createSenderDomainVerification({
+        workspaceId: state.deps.workspaceId, httpClient: state.deps.httpClient,
+        findProvider: async ({ id }) => (await state.deps.loadCatalog({})).registry.get({ id })?.provider,
+        resolveCredential: async ({ id }) => state.deps.credentials.resolve({ catalog: await state.deps.loadCatalog({}), id }),
+        resolveDomainReadCredential,
+        readProviderId: async () => (await currentSetting(state)).transactional,
+        readSenderEmail: async () => state.options.readSenderEmail ? state.options.readSenderEmail() : undefined,
+    });
+}
+/** Separate requirements read with permission-only fallback; deadline covers provider calls, not setup.
+ * Registry validation guarantees domainRequirements when domainVerification is true.
+ * @complexity At most two provider calls; diagnostic output is capped at 1000 characters. */
+async function requestDomainRequirements(required, optional = {}) {
+    const { ctx, providerId, provider, domain } = required;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error("The mail provider could not list its required DNS records.")), optional.timeoutMs ?? 5_000);
+    });
+    try {
+        const result = await Promise.race([readMailDomain({ ctx, providerId, read: context => provider.domainRequirements(context, { domain }), resolveDomainReadCredential: required.resolveDomainReadCredential }), timeout]);
+        if (result.status === "ok")
+            return result.value;
+        throw new ToolInputError({ message: safeMailProviderText({ text: `${result.error.code}: ${result.error.message}` }, { secrets: credentialSecrets({ credential: ctx.credential }) }) });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Resolve requirements only for this workspace and its active transactional provider. */
+async function domainRequirements(required) {
+    const { state, resolveDomainReadCredential } = required;
+    if (required.workspaceId !== state.deps.workspaceId)
+        return null;
+    const [setting, catalog, domain] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), readSenderDomain(state)]);
+    const id = setting.transactional;
+    const provider = id === null ? undefined : catalog.registry.get({ id })?.provider;
+    if (!domain || !provider?.capabilities.domainVerification)
+        return null;
+    const { credential } = await providerCredential({ state, catalog, id: id });
+    const ctx = credential ? { workspaceId: state.deps.workspaceId, mode: "live", credential, httpClient: state.deps.httpClient } : null;
+    return ctx ? requestDomainRequirements({ ctx, providerId: id, provider, domain, resolveDomainReadCredential }, { timeoutMs: state.options.domainRequirementsTimeoutMs }) : null;
+}
+/** Unique lane keys resolve in parallel; each failed lookup records a safe check note. @complexity O(lanes). */
+async function laneCredentials(required) {
+    const { state, catalog, setting } = required;
+    const ids = [...new Set([setting.transactional, setting.bulk].filter((id) => id !== null))];
+    const lookup = (id) => state.deps.credentials.resolve({ catalog, id }).catch((err) => {
+        // Only a provider with a label reaches the store, so a thrown lookup has a defined label.
+        recordError({ state, error: { providerId: id, source: "check", message: state.deps.credentialFailureReason({ label: catalog.credentialLabelFor({ id }), err }) } });
+        return null;
+    });
+    const found = await Promise.all(ids.map(async (id) => [id, await lookup(id)]));
+    return new Map(found.filter((pair) => pair[1] !== null));
+}
+/** Row-list faults affect presence facts but do not prevent independent key resolution. */
+function statusCredentialFacts({ state, deps }) {
+    return deps.listCredentialFacts({}).catch((err) => {
+        recordError({ state, error: { providerId: null, source: "check", message: `the saved mail credentials could not be listed (${err instanceof Error ? err.message : String(err)})` } });
+        return [];
+    });
+}
+/** Unanswered/unsupported checks produce no sender warning; only no_sender means unset. */
+function statusDomainState(state) {
+    if (state === "no_sender")
+        return null;
+    return ["verified", "pending", "failed", "not_found"].includes(state) ? state : undefined;
+}
+/** Start independent reads together, then await lane keys and domain verification in that order.
+ * Null means no sender; an unanswered check stays undefined and must not claim a sender is missing.
+ * @complexity O(c + p) credential facts/providers, O(lanes) decrypts; domain work uses its own deadline. */
+async function computeStatusReport(required) {
+    const { state, deps, senderDomainVerification } = required;
+    const checkedAt = new Date(state.nowMs()).toISOString();
+    const records = statusCredentialFacts({ state, deps });
+    const [setting, catalog, rows] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), records, readSenderDomain(state)]);
+    const credentials = await laneCredentials({ state, catalog, setting });
+    const verdict = await senderDomainVerification();
+    const domainState = statusDomainState(verdict.state);
+    if (verdict.state === "unknown")
+        recordError({ state, error: { providerId: verdict.providerId, source: "check", message: "Provider domain check unavailable." } });
+    const status = computeMailStatus({ setting, registry: catalog.registry, hasCredential: id => credentials.has(id) }, domainState === undefined ? {} : { senderDomainState: domainState });
+    const { providers } = deps.describeProviders({ catalog, records: rows, setting });
+    return { ...status, providers, refusals: catalog.refusals, checkedAt, senderDomainVerification: verdict };
+}
+/** Failed sends overlay cached status immediately; configuration alone never proves sending. */
+function statusWithLastError({ state, report }) {
+    const sendFailed = state.lastError?.source === "send" && report.lanes.some(lane => lane.providerId === state.lastError?.providerId);
+    return state.lastError ? { ...report, state: sendFailed && report.state === "ready" ? "degraded" : report.state, lastError: state.lastError } : report;
+}
+/** Host descriptions receive fresh, parallel setting/catalog/metadata reads. Failures propagate. */
+async function describeProviders({ state, deps }) {
+    const [setting, catalog, records] = await Promise.all([currentSetting(state), state.deps.loadCatalog({}), deps.listCredentialFacts({})]);
+    return deps.describeProviders({ catalog, records, setting });
+}
+/** Selection checks require a hosted provider and a usable key; they send nothing. */
+async function checkProvider({ state, id }) {
+    const catalog = await state.deps.loadCatalog({});
+    const provider = catalog.registry.get({ id })?.provider;
+    if (!provider)
+        return { ok: false, reason: `'${id}' is not an installed mail provider (installed: ${catalog.registry.list().map(entry => entry.id).join(", ")})` };
+    if (!provider.capabilities.hosted)
+        return { ok: false, reason: `'${id}' only prints mail locally and never delivers it` };
+    const found = await providerCredential({ state, catalog, id });
+    return found.credential ? { ok: true, label: provider.label } : { ok: false, reason: `'${id}' ${found.reason}` };
+}
+/** Detach pending work and clear all provider/capability projections; errors retain their original precedence. */
+function invalidate(state) {
+    state.generation += 1;
+    state.inFlight.clear();
+    state.resolved.clear();
+    state.lastTransactional = undefined;
+}
+/**
+ * Build a lane router and its control surface. The host binds catalogs, secrets, safe copy and DTOs.
+ * Each send reads selection and metadata; boot starts resolution synchronously. Selection faults
+ * refuse safely; status/description setup faults propagate and are never cached.
+ * @complexity O(providers) cached mailers/flights; status holds one report for its TTL.
+ * @example const control = createResolvedMailer(hostPorts, { clock }); await control.ready;
+ */
+export function createResolvedMailer(required, optional = {}) {
+    const state = { deps: required, options: optional, nowMs: () => (optional.clock ?? { nowMs: () => Date.now() }).nowMs(),
+        warn: optional.warn ?? (message => console.warn(message)),
+        wrap: optional.wrapProviderMailer ?? (({ mailer }) => mailer), resolved: new Map(), inFlight: new Map(), warned: new Set(), generation: 0,
+        initialization: undefined, lastTransactional: undefined, lastError: undefined };
+    const ready = forLane({ state, lane: "transactional" }).then(() => undefined);
+    const mailer = createRouter(state);
+    const resolveDomainReadCredential = input => optional.resolveDomainReadCredential?.(input) ?? Promise.resolve(null);
+    const senderDomainVerification = createDomainVerification({ state, resolveDomainReadCredential });
+    const statusCache = createTtlCache({ load: () => computeStatusReport({ state, deps: required, senderDomainVerification }), ttlMs: optional.statusTtlMs ?? MAIL_STATUS_TTL_MS, nowMs: state.nowMs }, { minRefreshIntervalMs: 5_000 });
+    return {
+        mailer, ready, senderDomainVerification,
+        settle: async () => { await forLane({ state, lane: "transactional" }); },
+        status: async (options = {}) => statusWithLastError({ state, report: await statusCache.get(options) }),
+        describeProviders: () => describeProviders({ state, deps: required }),
+        invalidate: () => { invalidate(state); statusCache.invalidate(); },
+        laneReady: async ({ lane }) => (await forLane({ state, lane })).capabilities({}).driver !== "console",
+        checkProvider: input => checkProvider({ state, ...input }),
+        domainRequirements: input => domainRequirements({ state, ...input, resolveDomainReadCredential }),
+    };
+}
+//# sourceMappingURL=resolve-mailer.js.map

package/dist/mail/senders.d.ts

@@ -0,0 +1,5 @@
+/** Universal sender surface: importing it never loads SMTP, delivery policy or Node crypto. */
+export * from "./email-sender.js";
+export * from "./email-sender-registry.js";
+export * from "./prepare-sender-email.js";
+//# sourceMappingURL=senders.d.ts.map

package/dist/mail/senders.js

@@ -0,0 +1,5 @@
+/** Universal sender surface: importing it never loads SMTP, delivery policy or Node crypto. */
+export * from "./email-sender.js";
+export * from "./email-sender-registry.js";
+export * from "./prepare-sender-email.js";
+//# sourceMappingURL=senders.js.map

package/dist/secrets/credential-sets/vault.repo.memory.d.ts

@@ -24,10 +24,7 @@ export declare class InMemoryVaultRepo implements VaultRepoPort {
     /** O(n) memory scan, n stored rows; clones only the default, never its siblings. */
     findDefault(input: VaultDefaultQuery, _options?: VaultOptions): Promise<VaultRecord | null>;
     list(input: VaultQuery, _options?: VaultOptions): Promise<VaultRecord[]>;
-    put(input: {
-        record: VaultRecord;
-        expectedRevision: number | null;
-    }, _options?: VaultOptions): Promise<VaultRecord>;
+    put(input: Parameters<VaultRepoPort["put"]>[0], _options?: VaultOptions): Promise<VaultRecord>;
     /** Synchronous mutation owner shared with batch staging; default moves never re-seal. */
     private putRecord;
     patchMeta(input: {

package/dist/secrets/credential-sets/vault.repo.memory.js

@@ -81,7 +81,9 @@ export class InMemoryVaultRepo {
         const group = this.groupRows({ groupKey });
         if (group.some(row => row.id !== record.id && row.label === record.label))
             throw new VaultError({ code: "conflict" });
-        const saved = structuredClone({ ...record, isDefault: record.isDefault || group.length === 0 });
+        // Auto-select the first row so an ordinary save is usable without a separate default action.
+        // Explicit false opts out, keeping unattached project keys from becoming vendor defaults.
+        const saved = structuredClone({ ...record, isDefault: record.isDefault ?? (group.length === 0) });
         // Clear first, matching a SQL partial UNIQUE index; no transient duplicate default is required.
         if (saved.isDefault)
             this.clearDefaults({ group });

package/dist/secrets/credential-sets/vault.service.d.ts

@@ -1,5 +1,5 @@
 import type { KeyringPort, SecretSealerPort } from "../ports.js";
-import { type VaultContext, type VaultIdentity, type VaultMeta, type VaultMetaParsers, type VaultCopyResult, type VaultDefaultQuery, type VaultOptions, type VaultQuery, type VaultRecord, type VaultRepoPort, type VaultSummary } from "./vault.types.js";
+import { type VaultContext, type VaultIdentity, type VaultMeta, type VaultMetaParsers, type VaultCopyResult, type VaultDefaultQuery, type VaultOptions, type VaultQuery, type VaultPutRecord, type VaultRepoPort, type VaultSummary } from "./vault.types.js";
 export interface VaultServiceDeps {
     repo: VaultRepoPort;
     keyring: KeyringPort;
@@ -24,10 +24,10 @@ export interface VaultPutInput extends VaultContext {
      * Creation requires a payload (which may be null). Payloads are always sealed JSON.
      */
     payload?: VaultMeta | null | undefined;
-    /** Omitted preserves same-group default status; a provider move starts with false and the
-     * repository applies its first-row rule. Explicit true selects the destination default.
+    /** Omitted preserves same-group default status; creation/provider moves let the repository
+     * apply its first-row rule. Explicit false opts out; true selects the destination default.
      */
-    isDefault?: boolean;
+    isDefault?: boolean | undefined;
     /** A host-selected token, never a URI or serialized connection object. */
     hintToken?: string;
 }
@@ -50,6 +50,7 @@ export declare class SecretsVaultService {
     constructor(deps: VaultServiceDeps, _options?: VaultOptions);
     private authorize;
     private parse;
+    /** Resolve a matching identity; deletion can retain legacy metadata without interpreting it. */
     private find;
     private seal;
     private open;
@@ -61,14 +62,18 @@ export declare class SecretsVaultService {
      * Prepared records contain envelopes and stay private to the host, never a public read model.
      * @example const record = await vault.prepare(input); await repo.put({ record, expectedRevision: input.expectedRevision }); // inside the host transaction
      */
-    prepare(input: VaultPutInput, _options?: VaultOptions): Promise<VaultRecord>;
+    prepare(input: VaultPutInput, _options?: VaultOptions): Promise<VaultPutRecord>;
     /** Resolve the target identity and apply the service-level CAS precheck. */
     private findForPut;
     private parsePutMeta;
     /** Omitted payload keeps the existing envelope and hints without opening or sealing. */
     private putEnvelope;
-    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership. */
-    get(input: VaultIdentity, _options?: VaultOptions): Promise<{
+    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership.
+     * `provider`, when given, must match the row's group before its envelope is opened (a stale
+     * selection never decrypts another group's secret). */
+    get(input: VaultIdentity, { provider }?: {
+        provider?: string;
+    }): Promise<{
         summary: VaultSummary;
         payload: VaultMeta | null;
     } | null>;
@@ -103,7 +108,8 @@ export declare class SecretsVaultService {
     private copyRow;
     /** Guarded read of the source row, then a CAS write of the resealed target row. */
     private transferRow;
-    /** Overwrite keeps the target's default, revision chain and creation time. */
+    /** Overwrite keeps the target's default, revision chain and creation time. A new copy leaves
+     * placement unspecified, so the repo's first-row rule applies (never the source's default flag). */
     private writeCopy;
     /** Human-managed scoped inventory. No envelope or plaintext is opened or returned. */
     list(input: VaultQuery, _options?: VaultOptions): Promise<VaultSummary[]>;
@@ -116,7 +122,9 @@ export declare class SecretsVaultService {
     rotate(input: VaultIdentity & {
         expectedRevision: number;
     }, _options?: VaultOptions): Promise<VaultSummary>;
-    /** Idempotent for missing rows; existing rows require matching context and revision. */
+    /** Idempotent for missing rows; existing rows require matching context and revision.
+     * Deletion needs no metadata interpretation, so unupgraded legacy rows remain removable.
+     */
     delete(input: VaultIdentity & {
         expectedRevision: number;
     }, _options?: VaultOptions): Promise<boolean>;

package/dist/secrets/credential-sets/vault.service.js

@@ -81,13 +81,15 @@ export class SecretsVaultService {
         assertContext(record);
         return { ...record, meta: this.deps.metaParsers[record.kind]({ meta: record.meta, provider: record.provider }) };
     }
-    async find(input) {
+    /** Resolve a matching identity; deletion can retain legacy metadata without interpreting it. */
+    async find(input, { parseMeta = true } = {}) {
         const record = await this.deps.repo.find({ workspaceId: input.workspaceId, id: input.id });
         if (!record)
             return null;
         if (buildVaultAad(input) !== buildVaultAad(record))
             throw new VaultError({ code: "context" });
-        return this.parse(record);
+        assertContext(record);
+        return parseMeta ? this.parse(record) : record;
     }
     async seal(input) {
         if (input.payload === null)
@@ -137,7 +139,7 @@ export class SecretsVaultService {
         const { sealed, last4, tokenLength } = await this.putEnvelope({ input, identity, existing });
         const now = this.deps.now({});
         return { ...identity, provider: input.provider, label: input.label, meta, sealed,
-            isDefault: input.isDefault ?? (existing !== null && existing.provider === input.provider && existing.isDefault),
+            isDefault: input.isDefault ?? (existing !== null && existing.provider === input.provider ? existing.isDefault : undefined),
             revision: (input.expectedRevision ?? 0) + 1, last4, tokenLength,
             createdAt: existing === null ? now : existing.createdAt, updatedAt: now };
     }
@@ -174,11 +176,15 @@ export class SecretsVaultService {
             ? credentialTokenHint({ token: input.hintToken }) : null;
         return { sealed, last4: hint?.last4 ?? null, tokenLength: hint?.length ?? null };
     }
-    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership. */
-    async get(input, _options = {}) {
+    /** Authorized runtime read; returns plaintext only to the caller that supplied exact ownership.
+     * `provider`, when given, must match the row's group before its envelope is opened (a stale
+     * selection never decrypts another group's secret). */
+    async get(input, { provider } = {}) {
         assertContext(input);
         await this.authorize({ action: "get", context: input });
         const record = await this.find(input);
+        if (record && provider !== undefined && record.provider !== provider)
+            throw new VaultError({ code: "context" });
         return record ? { summary: summary(record), payload: await this.open(record) } : null;
     }
     /** Singleton runtime read using one provider-independent lookup. Full expected ownership and
@@ -273,14 +279,15 @@ export class SecretsVaultService {
         const last4 = summary(await this.writeCopy({ source, record, targetIdentity, existing })).last4;
         return { status: "copied", ...(last4 ? { last4 } : {}) };
     }
-    /** Overwrite keeps the target's default, revision chain and creation time. */
+    /** Overwrite keeps the target's default, revision chain and creation time. A new copy leaves
+     * placement unspecified, so the repo's first-row rule applies (never the source's default flag). */
     async writeCopy({ source, record, targetIdentity, existing }) {
         if (existing && !isCompatibleOverwrite({ existing, record }))
             throw new VaultError({ code: "context" });
         const now = this.deps.now({});
         const placement = existing
             ? { isDefault: existing.isDefault, revision: existing.revision + 1, createdAt: existing.createdAt }
-            : { isDefault: false, revision: 1, createdAt: now };
+            : { isDefault: undefined, revision: 1, createdAt: now };
         const candidate = this.parse({ ...record, ...targetIdentity, ...placement, updatedAt: now });
         candidate.sealed = await this.seal({ context: targetIdentity, payload: await source.open(record) });
         // Reuse the source's hint policy without guessing a token field from a structured payload.
@@ -328,11 +335,13 @@ export class SecretsVaultService {
         return summary(this.parse(await this.deps.repo.put({ expectedRevision: input.expectedRevision,
             record: { ...existing, sealed, revision: existing.revision + 1, updatedAt: this.deps.now({}) } })));
     }
-    /** Idempotent for missing rows; existing rows require matching context and revision. */
+    /** Idempotent for missing rows; existing rows require matching context and revision.
+     * Deletion needs no metadata interpretation, so unupgraded legacy rows remain removable.
+     */
     async delete(input, _options = {}) {
         assertContext(input);
         await this.authorize({ action: "delete", context: input });
-        const existing = await this.find(input);
+        const existing = await this.find(input, { parseMeta: false });
         if (!existing)
             return false;
         if (existing.revision !== input.expectedRevision)

package/dist/secrets/credential-sets/vault.types.d.ts

@@ -42,6 +42,12 @@ export interface VaultRecord extends VaultIdentity {
 export type VaultSummary = Omit<VaultRecord, "sealed"> & {
     configured: boolean;
 };
+/** Unspecified placement lets the repo auto-default a group's first row; false opts out.
+ * Persisted records and read models always contain a concrete boolean.
+ */
+export type VaultPutRecord = Omit<VaultRecord, "isDefault"> & {
+    isDefault?: boolean | undefined;
+};
 export interface VaultQuery {
     workspaceId: string;
     kind: VaultKind;
@@ -65,7 +71,7 @@ export interface VaultSingletonQuery {
 /** Ordered CAS operations; default side effects affect later operations' revisions. */
 export type VaultBatchOp = {
     put: {
-        record: VaultRecord;
+        record: VaultPutRecord;
         expectedRevision: number | null;
     };
 } | {
@@ -129,7 +135,7 @@ export interface VaultRepoPort {
     }, options?: VaultOptions): Promise<VaultBatchResult[]>;
     list(input: VaultQuery, options?: VaultOptions): Promise<VaultRecord[]>;
     put(input: {
-        record: VaultRecord;
+        record: VaultPutRecord;
         expectedRevision: number | null;
     }, options?: VaultOptions): Promise<VaultRecord>;
     /** Service-validated patch: top-level keys are plain JSON-path identifiers. */
@@ -148,11 +154,11 @@ export interface VaultRepoPort {
 }
 /** Unambiguous scope encoding keeps adapter default/identity checks on the same contract. */
 export declare function vaultGroupKey({ record }: {
-    record: VaultRecord;
+    record: VaultDefaultQuery;
 }, _options?: VaultOptions): string;
 /** Adapters guard CAS and immutable identity even for callers below the service. */
 export declare function assertVaultReplacement({ record, existing, expectedRevision }: {
-    record: VaultRecord;
+    record: VaultPutRecord;
     existing: VaultRecord | null;
     expectedRevision: number | null;
 }, _options?: VaultOptions): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/platform",
-  "version": "0.6.12",
+  "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": {
@@ -22,6 +22,7 @@
       "./secrets/testing": "node",
       "./http/guarded": "node",
       "./mail": "node",
+      "./mail/senders": "universal",
       "./mail/smtp": "node",
       "./fs/guarded-reader": "node",
       "./fs/durable-json": "node",
@@ -106,6 +107,11 @@
       "import": "./dist/mail/index.js",
       "default": "./dist/mail/index.js"
     },
+    "./mail/senders": {
+      "types": "./dist/mail/senders.d.ts",
+      "import": "./dist/mail/senders.js",
+      "default": "./dist/mail/senders.js"
+    },
     "./mail/smtp": {
       "types": "./dist/mail/smtp.d.ts",
       "import": "./dist/mail/smtp.js",
@@ -200,7 +206,7 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@jini-ai/core": "^0.6.12"
+    "@jini-ai/core": "^0.6.15-rc.2"
   },
   "publishConfig": {
     "access": "public",