@openlup/platform 0.15.0 → 0.17.0

package/dist/communications/contracts/transactionalDelivery.d.ts

@@ -0,0 +1,42 @@
+export interface TransactionalDeliveryCommand {
+    readonly idempotencyKey: string;
+    /** Opaque recipient reference; never persisted outside the command fingerprint. */
+    readonly recipientReference: string;
+    /** Opaque template reference; never persisted outside the command fingerprint. */
+    readonly templateReference: string;
+    /** Optional bounded reference to an expiring/revocable access grant. */
+    readonly accessGrantReference?: string;
+}
+export type TransactionalDeliveryReceipt = {
+    readonly idempotencyKey: string;
+    readonly commandFingerprint: string;
+    readonly state: "accepted";
+    readonly deliveryReference: string;
+    readonly errorCode: null;
+    readonly attemptCount: number;
+} | {
+    readonly idempotencyKey: string;
+    readonly commandFingerprint: string;
+    readonly state: "failed";
+    readonly deliveryReference: null;
+    readonly errorCode: string;
+    readonly attemptCount: number;
+};
+export interface TransactionalDeliveryReceiptStore {
+    readReceipt(idempotencyKey: string): Promise<TransactionalDeliveryReceipt | null>;
+    recordAccepted(input: {
+        idempotencyKey: string;
+        commandFingerprint: string;
+        deliveryReference: string;
+    }): Promise<TransactionalDeliveryReceipt>;
+    recordFailed(input: {
+        idempotencyKey: string;
+        commandFingerprint: string;
+        errorCode: string;
+    }): Promise<TransactionalDeliveryReceipt>;
+}
+export interface CapturedTransactionalDeliveryPort {
+    deliver(command: TransactionalDeliveryCommand): Promise<{
+        deliveryReference: string;
+    }>;
+}

package/dist/communications/contracts/transactionalDelivery.js

@@ -0,0 +1 @@
+export {};

package/dist/communications/contracts/types.d.ts

@@ -0,0 +1,46 @@
+type COMMUNICATION_CHANNEL = "email";
+type EMAIL_SEND_STATUSES = "queued" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "skipped";
+type EMAIL_SEND_SKIP_REASONS = "sequence_paused" | "already_sent" | "template_unavailable" | "race_lost" | "policy_blocked" | "admin_disabled";
+export type CommunicationChannel = COMMUNICATION_CHANNEL;
+/** The host supplies its persisted provider vocabulary. */
+export type CommunicationProvider<Provider extends string = string> = Provider;
+export type EmailSendStatus = EMAIL_SEND_STATUSES;
+export type EmailSendSkipReason = EMAIL_SEND_SKIP_REASONS;
+type COMMUNICATION_PURPOSES = "transactional" | "tester_program" | "marketing_launch_offer" | "marketing_newsletter" | "subscription_dunning" | "admin_notification";
+type COMMUNICATION_PERMISSION_STATES = "unknown" | "granted" | "denied" | "suppressed";
+type COMMUNICATION_POLICY_DECISIONS = "allowed" | "blocked";
+export type CommunicationPurpose = COMMUNICATION_PURPOSES;
+export type CommunicationPermissionState = COMMUNICATION_PERMISSION_STATES;
+export type CommunicationPolicyDecision = COMMUNICATION_POLICY_DECISIONS;
+export interface CommunicationRecipientRef {
+    system: "supabase";
+    table: "testers";
+    id: string;
+    email: string | null;
+}
+export interface EmailTemplateRef {
+    slug: string;
+    locale: string | null;
+}
+export interface EmailSendDedupeKeyInput {
+    recipientId: string;
+    templateSlug: string;
+}
+export type EmailSendDecision = {
+    outcome: "send";
+} | {
+    outcome: "skip";
+    reason: EmailSendSkipReason;
+    existingMessageId: string | null;
+};
+export interface EmailMessageReadModel<Provider extends string = string> {
+    id: string;
+    channel: CommunicationChannel;
+    recipientId: string;
+    templateSlug: string;
+    status: EmailSendStatus;
+    provider: CommunicationProvider<Provider> | null;
+    providerMessageId: string | null;
+    skippedReason: EmailSendSkipReason | null;
+}
+export {};

package/dist/communications/contracts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/communications/contribution.d.ts

@@ -0,0 +1,10 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Host-selected schema inventory: managed and direct installations have different objects. */
+export declare function createCommunicationsContribution(options: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    routes?: Contribution["routes"];
+    handlers?: Contribution["handlers"];
+    schedules?: Contribution["schedules"];
+    requiredPorts?: readonly string[];
+}): Contribution;

package/dist/communications/contribution.js

@@ -0,0 +1,24 @@
+/** Host-selected schema inventory: managed and direct installations have different objects. */
+export function createCommunicationsContribution(options) {
+    const routes = options.routes ?? [];
+    const handlers = options.handlers ?? [];
+    const schedules = options.schedules ?? [];
+    return {
+        manifest: {
+            name: "@openlup/platform", version: options.version, kind: "rail",
+            module: {
+                id: "communications", kind: "capability", provides: ["./communications", "./communications/contracts"],
+                dependsOn: [
+                    { module: "data", entries: ["./data"] },
+                    { module: "identity", entries: ["./identity"] },
+                    { module: "http", entries: ["./http"] },
+                ],
+            },
+            requiredSchema: options.requiredSchema,
+            emits: [], handles: handlers.map((handler) => handler.eventType),
+            schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), routes: routes.map((route) => route.id),
+            requiredPorts: [...new Set(options.requiredPorts ?? [])], env: [],
+        },
+        handlers, schedules, routes,
+    };
+}

package/dist/communications/deliveryReconciliation.d.ts

@@ -0,0 +1,64 @@
+export interface DeliveryPollCandidate {
+    id: string;
+    messageId: string;
+}
+export interface DeliveryStatusRead {
+    ok: boolean;
+    httpStatus: number;
+    recipientEmail: string | null;
+}
+/** The host maps its protocol to an opaque event type and terminal classification. */
+export interface DeliveryPollObservation {
+    eventType: string;
+    terminal: boolean;
+}
+export interface DeliveryReconciliationPort {
+    findFrozenSends(input: {
+        now: string;
+        graceMinutes: number;
+        limit: number;
+    }): Promise<DeliveryPollCandidate[]>;
+    applyPolledEvent(input: {
+        sendId: string;
+        messageId: string;
+        eventType: string;
+        eventAt: string;
+        recipientEmail: string | null;
+    }): Promise<void>;
+    recordPollAttempt(input: {
+        sendId: string;
+        attemptedAt: string;
+    }): Promise<void>;
+    recordSendNotFound(input: {
+        sendId: string;
+        threshold: number;
+    }): Promise<{
+        abandoned: boolean;
+    }>;
+}
+export declare const DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND = 3;
+export interface DeliveryReadFailureBreakdown {
+    notFound: number;
+    authFailed: number;
+    network: number;
+    providerError: number;
+    other: number;
+}
+export interface DeliveryReconciliationResult {
+    checked: number;
+    reconciled: number;
+    stillPending: number;
+    terminalPolled: number;
+    failures: number;
+    abandoned: number;
+    failureBreakdown: DeliveryReadFailureBreakdown;
+}
+/** Sequential bounded polling around one host-owned atomic convergence writer. */
+export declare function runDeliveryReconciliation<Read extends DeliveryStatusRead>(input: {
+    port: DeliveryReconciliationPort;
+    readEmail: (messageId: string) => Promise<Read>;
+    observationFor: (read: Read) => DeliveryPollObservation | null;
+    now: string;
+    graceMinutes: number;
+    limit: number;
+}): Promise<DeliveryReconciliationResult>;

package/dist/communications/deliveryReconciliation.js

@@ -0,0 +1,60 @@
+export const DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND = 3;
+function classifyReadFailure(breakdown, httpStatus) {
+    if (httpStatus === 404)
+        breakdown.notFound += 1;
+    else if (httpStatus === 401 || httpStatus === 403)
+        breakdown.authFailed += 1;
+    else if (httpStatus === 0)
+        breakdown.network += 1;
+    else if (httpStatus >= 500 && httpStatus <= 599)
+        breakdown.providerError += 1;
+    else
+        breakdown.other += 1;
+}
+/** Sequential bounded polling around one host-owned atomic convergence writer. */
+export async function runDeliveryReconciliation(input) {
+    const result = {
+        checked: 0, reconciled: 0, stillPending: 0, terminalPolled: 0, failures: 0, abandoned: 0,
+        failureBreakdown: { notFound: 0, authFailed: 0, network: 0, providerError: 0, other: 0 },
+    };
+    const frozen = await input.port.findFrozenSends({ now: input.now, graceMinutes: input.graceMinutes, limit: input.limit });
+    for (const send of frozen) {
+        result.checked += 1;
+        const read = await input.readEmail(send.messageId);
+        if (read.httpStatus !== 404) {
+            try {
+                await input.port.recordPollAttempt({ sendId: send.id, attemptedAt: input.now });
+            }
+            catch {
+                // Fairness bookkeeping failure must not discard observed delivery truth.
+                result.failures += 1;
+            }
+        }
+        if (!read.ok) {
+            result.failures += 1;
+            classifyReadFailure(result.failureBreakdown, read.httpStatus);
+            if (read.httpStatus === 404) {
+                const { abandoned } = await input.port.recordSendNotFound({ sendId: send.id, threshold: DELIVERY_POLL_ABANDON_AFTER_NOT_FOUND });
+                if (abandoned)
+                    result.abandoned += 1;
+            }
+            continue;
+        }
+        const observation = input.observationFor(read);
+        if (!observation) {
+            result.stillPending += 1;
+            continue;
+        }
+        try {
+            await input.port.applyPolledEvent({ sendId: send.id, messageId: send.messageId,
+                eventType: observation.eventType, eventAt: input.now, recipientEmail: read.recipientEmail });
+            result.reconciled += 1;
+            if (observation.terminal)
+                result.terminalPolled += 1;
+        }
+        catch {
+            result.failures += 1;
+        }
+    }
+    return result;
+}

package/dist/communications/emailEgress.d.ts

@@ -0,0 +1,38 @@
+import type { AuthEmailTransportPort } from "./contracts/authEmail.js";
+import type { EmailMessage, EmailSendResult, EmailTransport } from "./emailTransport.js";
+export interface EmailEgressContext {
+    mode: "production" | "sandbox_direct" | "sandbox_sink";
+    reason: string;
+    intendedRecipient: string;
+    recipient: string;
+    /** Selected by the host; consumed only by its concrete sender, never logged. */
+    credential: string;
+    environmentTag: "production" | "non_production";
+}
+export type EmailEgressDecision = EmailEgressContext | {
+    mode: "drop";
+    reason: string;
+} | {
+    mode: "blocked";
+    reason: string;
+};
+export type EmailEgressPolicy = (intendedRecipient: string) => EmailEgressDecision | Promise<EmailEgressDecision>;
+/**
+ * Host composition bridge for an implementation that already enforces egress
+ * internally. This is a trust boundary: its sender must itself refuse unknown
+ * policy before effects. New network adapters should use createGuardedEmailTransport.
+ * Neither a provider name nor an object property establishes admission.
+ */
+export declare function admitPolicyEnforcedEmailTransport<T extends EmailTransport>(transport: T): T;
+/** Mandatory boundary for supported injected transports; raw objects fail closed. */
+export declare function guardEmailTransport(transport: EmailTransport): EmailTransport;
+/** Construct a network adapter whose sender sees only a validated host decision. */
+export declare function createGuardedEmailTransport(input: {
+    providerKind: string;
+    policy: EmailEgressPolicy;
+    send: (message: EmailMessage, context: Readonly<EmailEgressContext>) => Promise<EmailSendResult>;
+}): EmailTransport;
+/** Preserve the Auth envelope/result mapping while retaining package admission. */
+export declare function createAuthEmailTransport(transport: EmailTransport): AuthEmailTransportPort;
+/** Raw Auth closures must compose through the admitted email transport bridge. */
+export declare function guardAuthEmailTransport(transport: AuthEmailTransportPort): AuthEmailTransportPort;

package/dist/communications/emailEgress.js

@@ -0,0 +1,100 @@
+const admitted = new WeakSet();
+const admittedAuth = new WeakSet();
+/**
+ * Host composition bridge for an implementation that already enforces egress
+ * internally. This is a trust boundary: its sender must itself refuse unknown
+ * policy before effects. New network adapters should use createGuardedEmailTransport.
+ * Neither a provider name nor an object property establishes admission.
+ */
+export function admitPolicyEnforcedEmailTransport(transport) {
+    admitted.add(transport);
+    return transport;
+}
+/** Mandatory boundary for supported injected transports; raw objects fail closed. */
+export function guardEmailTransport(transport) {
+    if (admitted.has(transport))
+        return transport;
+    return { providerKind: transport.providerKind, send: async () => refused("email_egress_unadmitted") };
+}
+/** Construct a network adapter whose sender sees only a validated host decision. */
+export function createGuardedEmailTransport(input) {
+    return admitPolicyEnforcedEmailTransport({
+        providerKind: input.providerKind,
+        async send(message) {
+            let decision;
+            try {
+                decision = await input.policy(message.to);
+            }
+            catch {
+                return refused("email_egress_policy_unavailable");
+            }
+            if (!validDecision(decision, message.to))
+                return refused("email_egress_policy_invalid");
+            if (decision.mode === "blocked")
+                return refused("email_egress_blocked", decision.reason);
+            if (decision.mode === "drop")
+                return {
+                    outcome: { ok: true, resendId: null, httpStatus: 0, providerError: null, aborted: false,
+                        suppressed: "drop", egressMode: "drop", egressReason: decision.reason },
+                    providerResponse: { suppressed: "drop", egress_reason: decision.reason },
+                };
+            const context = Object.freeze({ ...decision });
+            const result = await input.send({ ...message, to: context.recipient }, context);
+            return { ...result, outcome: { ...result.outcome, egressMode: context.mode, egressReason: context.reason } };
+        },
+    });
+}
+function validDecision(value, intended) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const d = value;
+    // Policy diagnostics are bounded codes, never arbitrary exception/secret text.
+    if (typeof d.reason !== "string" || !/^[a-z][a-z0-9_]{0,79}$/.test(d.reason))
+        return false;
+    if (d.mode === "drop" || d.mode === "blocked")
+        return Object.keys(d).every((key) => key === "mode" || key === "reason");
+    if (d.mode !== "production" && d.mode !== "sandbox_direct" && d.mode !== "sandbox_sink")
+        return false;
+    if (!Object.keys(d).every((key) => ["mode", "reason", "intendedRecipient", "recipient", "credential", "environmentTag"].includes(key)))
+        return false;
+    if (!mailbox(intended) || d.intendedRecipient !== intended || !mailbox(d.recipient))
+        return false;
+    if (d.mode !== "sandbox_sink" && d.recipient !== intended)
+        return false;
+    if (typeof d.credential !== "string" || !d.credential.trim())
+        return false;
+    return d.environmentTag === (d.mode === "production" ? "production" : "non_production");
+}
+function mailbox(value) {
+    return typeof value === "string" && /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/.test(value);
+}
+function refused(code, reason) {
+    return { outcome: { ok: false, resendId: null, httpStatus: 0, providerError: code, aborted: false,
+            ...(reason ? { egressReason: reason } : {}) }, providerResponse: { egress_reason: code } };
+}
+/** Preserve the Auth envelope/result mapping while retaining package admission. */
+export function createAuthEmailTransport(transport) {
+    const guarded = guardEmailTransport(transport);
+    const auth = {
+        providerKind: transport.providerKind,
+        async send(message) {
+            const result = await guarded.send({ from: message.sender, to: message.recipient,
+                subject: message.subject, html: message.html, text: message.text });
+            return { outcome: { ...result.outcome, messageId: result.outcome.resendId }, providerResponse: result.providerResponse };
+        },
+    };
+    admittedAuth.add(auth);
+    return auth;
+}
+/** Raw Auth closures must compose through the admitted email transport bridge. */
+export function guardAuthEmailTransport(transport) {
+    if (admittedAuth.has(transport))
+        return transport;
+    return {
+        providerKind: transport.providerKind,
+        async send() {
+            const result = refused("email_egress_unadmitted");
+            return { outcome: { ...result.outcome, messageId: null }, providerResponse: result.providerResponse };
+        },
+    };
+}

package/dist/communications/emailHealthAssessment.d.ts

@@ -0,0 +1,39 @@
+import type { EmailHealthMetrics } from "./emailHealthMetricsPort.js";
+/**
+ * Pure email-health assessment layer: env-derived thresholds plus the
+ * healthy/unhealthy verdict over the delivery metrics. Extracted from
+ * `api/_cron/emailHealthWatchdogJob.ts` (which sat at the 300-LOC source cap)
+ * so the incident-driven `permanent_delivery_failure` breach could land here
+ * with unit coverage and no database in the loop.
+ */
+type Env = Record<string, string | undefined>;
+export interface EmailHealthThresholds {
+    windowMinutes: number;
+    stuckMinutes: number;
+    minAttemptsForRatio: number;
+    maxFailureRatio: number;
+    maxStuck: number;
+    /**
+     * Absolute ceiling on in-window deliveries that ended `status='failed'`
+     * (handler-final loss of a customer notification: outbox discard,
+     * max-attempts exhaustion). Default 0 — a single lost email breaches.
+     * Bounces/complaints are separate statuses and stay ratio-only.
+     */
+    maxPermanentFailures: number;
+}
+export interface EmailHealthBreach {
+    code: string;
+    detail: string;
+}
+export interface EmailHealthAssessment {
+    healthy: boolean;
+    failureRatio: number;
+    breaches: EmailHealthBreach[];
+}
+export declare function readEmailHealthThresholds(env: Env): EmailHealthThresholds;
+/**
+ * Pure decision: turn raw counts into a healthy/unhealthy verdict. Kept side
+ * effect-free so the thresholds logic is unit-tested without a database.
+ */
+export declare function evaluateEmailHealth(metrics: EmailHealthMetrics, thresholds: EmailHealthThresholds): EmailHealthAssessment;
+export {};

package/dist/communications/emailHealthAssessment.js

@@ -0,0 +1,59 @@
+export function readEmailHealthThresholds(env) {
+    return {
+        windowMinutes: positiveInt(env.EMAIL_HEALTH_WINDOW_MINUTES, 60),
+        stuckMinutes: positiveInt(env.EMAIL_HEALTH_STUCK_MINUTES, 30),
+        minAttemptsForRatio: positiveInt(env.EMAIL_HEALTH_MIN_ATTEMPTS_FOR_RATIO, 5),
+        maxFailureRatio: clampRatio(env.EMAIL_HEALTH_MAX_FAILURE_RATIO, 0.5),
+        maxStuck: nonNegativeInt(env.EMAIL_HEALTH_MAX_STUCK, 0),
+        maxPermanentFailures: nonNegativeInt(env.EMAIL_HEALTH_MAX_PERMANENT_FAILURES, 0),
+    };
+}
+/**
+ * Pure decision: turn raw counts into a healthy/unhealthy verdict. Kept side
+ * effect-free so the thresholds logic is unit-tested without a database.
+ */
+export function evaluateEmailHealth(metrics, thresholds) {
+    const failureRatio = metrics.attempted > 0 ? metrics.failed / metrics.attempted : 0;
+    const breaches = [];
+    if (metrics.attempted >= thresholds.minAttemptsForRatio && failureRatio > thresholds.maxFailureRatio) {
+        breaches.push({
+            code: "failure_ratio",
+            detail: `${metrics.failed}/${metrics.attempted} (${(failureRatio * 100).toFixed(1)}%) > ${(thresholds.maxFailureRatio * 100).toFixed(1)}%`,
+        });
+    }
+    // Absolute, ratio-independent: one terminally-failed delivery is one
+    // customer notification we finally did not send. Incident 2026-07-24: a
+    // single discarded payment-recovery email stayed invisible because the
+    // ratio breach needs minAttemptsForRatio sends in the window.
+    if (metrics.permanentFailures > thresholds.maxPermanentFailures) {
+        breaches.push({
+            code: "permanent_delivery_failure",
+            detail: `${metrics.permanentFailures} delivery(ies) terminally failed > ${thresholds.maxPermanentFailures}`,
+        });
+    }
+    if (metrics.stuckProcessing > thresholds.maxStuck) {
+        breaches.push({
+            code: "stuck_processing",
+            detail: `${metrics.stuckProcessing} email(s) stuck in 'processing' > ${thresholds.stuckMinutes}m`,
+        });
+    }
+    if (metrics.stuckScheduled > thresholds.maxStuck) {
+        breaches.push({
+            code: "stuck_scheduled",
+            detail: `${metrics.stuckScheduled} scheduled email(s) overdue and undispatched`,
+        });
+    }
+    return { healthy: breaches.length === 0, failureRatio, breaches };
+}
+function positiveInt(raw, fallback) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+function nonNegativeInt(raw, fallback) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+function clampRatio(raw, fallback) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 && n <= 1 ? n : fallback;
+}

package/dist/communications/emailHealthMetricsPort.d.ts

@@ -0,0 +1,17 @@
+export interface EmailHealthMetrics {
+    attempted: number;
+    sent: number;
+    failed: number;
+    delayed: number;
+    /**
+     * In-window rows that ended `status='failed'` — handler-final loss of a
+     * customer notification (outbox discard / max-attempts). Distinct from
+     * `failed` above, which also counts bounces/complaints/missed for the
+     * ratio signal.
+     */
+    permanentFailures: number;
+    /** `processing` rows whose last transition is older than the stuck threshold. */
+    stuckProcessing: number;
+    /** `planned`/`queued` rows past their `expected_send_at` but still not sent. */
+    stuckScheduled: number;
+}

package/dist/communications/emailHealthMetricsPort.js

@@ -0,0 +1 @@
+export {};

package/dist/communications/emailNotificationControl.d.ts

@@ -0,0 +1,27 @@
+export interface EmailNotificationControlPort {
+    isEnabled(slug: string, signal: AbortSignal): Promise<boolean>;
+}
+export interface EmailNotificationControlClient {
+    from(table: string): EmailNotificationControlQueryBuilder;
+}
+interface EmailNotificationControlQueryBuilder {
+    select(columns: string): EmailNotificationControlQueryBuilder;
+    eq(column: string, value: unknown): EmailNotificationControlQueryBuilder;
+    maybeSingle(): PromiseLike<{
+        data: unknown;
+        error: {
+            code?: string;
+            message?: string;
+        } | null;
+    }>;
+}
+export declare function createEmailNotificationControlPort(client: EmailNotificationControlClient, createPolicy: (client: EmailNotificationControlClient) => {
+    shouldDeliver(input: {
+        slug: string;
+        signal: AbortSignal;
+    }): Promise<{
+        allow: boolean;
+    }>;
+}): EmailNotificationControlPort;
+export declare const createSupabaseEmailNotificationControlPort: typeof createEmailNotificationControlPort;
+export {};

package/dist/communications/emailNotificationControl.js

@@ -0,0 +1,10 @@
+export function createEmailNotificationControlPort(client, createPolicy) {
+    const policy = createPolicy(client);
+    return {
+        isEnabled(slug, signal) {
+            return policy.shouldDeliver({ slug, signal }).then((decision) => decision.allow);
+        },
+    };
+}
+// Compatibility alias for the pre-neutralization lifecycle consumer.
+export const createSupabaseEmailNotificationControlPort = createEmailNotificationControlPort;

package/dist/communications/emailObservation.d.ts

@@ -0,0 +1,28 @@
+/** An authenticated, decoded, environment-admitted observation. Evidence is opaque. */
+export interface EmailObservation {
+    eventType: string;
+    eventAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface EmailObservationPort {
+    findSend(messageId: string): Promise<{
+        id: string;
+    } | null>;
+    applyObservation(observation: EmailObservation & {
+        sendId: string;
+        messageId: string;
+    }): Promise<void>;
+    recordAttempt(attempt: EmailObservationDisposition): Promise<void>;
+}
+export type EmailObservationDisposition = {
+    outcome: "send_not_found";
+} | {
+    outcome: "processed";
+    sendId: string;
+};
+/** Lookup/apply failures propagate; attempt telemetry cannot overturn authoritative success. */
+export declare function processEmailObservation(input: {
+    port: EmailObservationPort;
+    messageId: string;
+    observation: () => EmailObservation;
+}): Promise<EmailObservationDisposition>;

package/dist/communications/emailObservation.js

@@ -0,0 +1,23 @@
+/** Lookup/apply failures propagate; attempt telemetry cannot overturn authoritative success. */
+export async function processEmailObservation(input) {
+    const send = await input.port.findSend(input.messageId);
+    let disposition;
+    if (!send) {
+        disposition = { outcome: "send_not_found" };
+    }
+    else {
+        await input.port.applyObservation({
+            sendId: send.id,
+            messageId: input.messageId,
+            ...input.observation(),
+        });
+        disposition = { outcome: "processed", sendId: send.id };
+    }
+    try {
+        await input.port.recordAttempt(disposition);
+    }
+    catch {
+        // Best-effort telemetry is separate from durable convergence.
+    }
+    return disposition;
+}