@openlup/platform 0.16.0 → 0.18.0

package/dist/communications/originPolicy.js

@@ -0,0 +1,100 @@
+export const EMAIL_DEFAULT_ORIGIN_ENV = "EMAIL_DEFAULT_ORIGIN";
+export const EMAIL_PRODUCTION_ORIGIN_HOSTS_ENV = "EMAIL_PRODUCTION_ORIGIN_HOSTS";
+export const COMMS_PRODUCTION_PROJECT_REF_ENV = "COMMS_PRODUCTION_PROJECT_REF";
+function clean(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}
+function resolveEnvironment(input) {
+    if (input.hiddenPreviewEnabled)
+        return "hidden_preview";
+    const value = clean(input.environment)?.toLowerCase().replace(/-/g, "_");
+    if (value === "hidden_preview" ||
+        value === "preview" ||
+        value === "staging" ||
+        value === "production" ||
+        value === "production_or_default") {
+        return value;
+    }
+    return "production_or_default";
+}
+export function normalizeEmailOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            return null;
+        if (!url.hostname)
+            return null;
+        return url.origin.replace(/\/+$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+export function isProductionEmailOrigin(origin, productionHosts) {
+    try {
+        return productionHosts.includes(new URL(origin).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+export function readEmailOriginConfiguration(env, fallback) {
+    const configuredDefault = env[EMAIL_DEFAULT_ORIGIN_ENV];
+    const configuredHosts = env[EMAIL_PRODUCTION_ORIGIN_HOSTS_ENV];
+    return {
+        defaultOrigin: configuredDefault === undefined ? fallback.defaultOrigin : configuredDefault,
+        productionEmailHosts: configuredHosts === undefined
+            ? fallback.productionEmailHosts
+            : configuredHosts
+                .split(/[,\s;]+/)
+                .map((host) => host.trim().toLowerCase())
+                .filter(Boolean),
+    };
+}
+function requiresExplicitNonProductionOrigin(environment) {
+    return environment === "hidden_preview" || environment === "preview" || environment === "staging";
+}
+export function resolveEmailOrigin(input) {
+    const environment = resolveEnvironment(input);
+    const explicit = clean(input.explicitBaseUrl) ??
+        clean(input.customerAuthRedirectOrigin) ??
+        clean(input.siteUrl);
+    if (!explicit) {
+        if (requiresExplicitNonProductionOrigin(environment)) {
+            return { ok: false, error: "hidden_preview_origin_required" };
+        }
+        const defaultOrigin = normalizeEmailOrigin(input.defaultOrigin);
+        if (!defaultOrigin)
+            return { ok: false, error: "invalid_email_origin" };
+        return {
+            ok: true,
+            origin: defaultOrigin,
+            source: "default",
+            resolved: {
+                origin: defaultOrigin,
+                source: "default",
+                environment,
+                production: isProductionEmailOrigin(defaultOrigin, input.productionEmailHosts),
+            },
+        };
+    }
+    const normalized = normalizeEmailOrigin(explicit);
+    if (!normalized)
+        return { ok: false, error: "invalid_email_origin" };
+    const production = isProductionEmailOrigin(normalized, input.productionEmailHosts);
+    if (requiresExplicitNonProductionOrigin(environment) && production) {
+        return { ok: false, error: "hidden_preview_origin_must_not_be_production" };
+    }
+    return {
+        ok: true,
+        origin: normalized,
+        source: "explicit",
+        resolved: {
+            origin: normalized,
+            source: "explicit",
+            environment,
+            production,
+        },
+    };
+}

package/dist/communications/postgresCommunicationSync.d.ts

@@ -0,0 +1,79 @@
+import type { SqlExecutor } from "@openlup/core/readiness";
+import type { PostgresDataGatewayEnv } from "../data/index.js";
+import type { CommunicationSyncStore } from "./communicationSyncWorker.js";
+import type { NewsletterSyncEventType, NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NativeCommunicationsOptions } from "./nativeOperations.js";
+/** Structural seam for the existing outbox store, scoped to this operation's transaction. */
+export interface NativeSyncRail {
+    claimBatch(input: {
+        eventTypes: string[];
+        knownEventTypes: string[];
+        batchSize: number;
+        visibilitySeconds: number;
+        maxAttempts: number;
+    }): Promise<{
+        id: string;
+        attempts: number;
+        metadata: Record<string, unknown>;
+    }[]>;
+    markProcessed(input: {
+        eventId: string;
+        claimToken: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        applied: boolean;
+    }>;
+    markFailed(input: {
+        eventId: string;
+        claimToken: string;
+        error: string;
+        outcome: "retry" | "discard";
+        baseDelaySeconds: number;
+        maxDelaySeconds: number;
+        maxAttempts: number;
+        snoozeSeconds: number;
+    }): Promise<{
+        status: string;
+    }>;
+}
+export interface NativeSyncRegistration {
+    sourceKey: string;
+    contactId: string;
+    normalizedEmail: string;
+    eventType: NewsletterSyncEventType;
+    purpose: NewsletterMarketingPurpose;
+    payload?: Record<string, unknown>;
+    originProviderKind?: string | null;
+    originProviderEventId?: string | null;
+    remoteProfileId?: string | null;
+    remoteListId?: string | null;
+}
+export interface NativeSyncOptions extends NativeCommunicationsOptions {
+    providerKind: string;
+    rail: (db: SqlExecutor) => NativeSyncRail;
+}
+export interface NativeCommunicationSyncStore extends CommunicationSyncStore {
+    registerWork(input: NativeSyncRegistration): Promise<{
+        id: string;
+    }>;
+    registerPreference(input: {
+        email: string;
+        purpose: "tester_program" | NewsletterMarketingPurpose;
+        state: "denied" | "suppressed";
+    }): Promise<{
+        updated: true;
+        email: string;
+        purpose: "tester_program" | NewsletterMarketingPurpose;
+        state: "denied" | "suppressed";
+        workId: string | null;
+        alreadySuppressed: boolean;
+    }>;
+    close(): Promise<void>;
+}
+export declare const nativeSyncEventType: (binding: string) => string;
+/** Trusted host transaction seam; registration validation remains shared with the standalone store. */
+export declare function registerNativeSyncWorkInTransaction(db: SqlExecutor, options: Pick<NativeSyncOptions, "binding" | "providerKind">, input: NativeSyncRegistration): Promise<{
+    id: string;
+}>;
+/** No sidecar claim/lease/drainer. Only runCommunicationSyncDispatch executes membership effects. */
+export declare function createPostgresCommunicationSyncStore(env: PostgresDataGatewayEnv, options: NativeSyncOptions): NativeCommunicationSyncStore;

package/dist/communications/postgresCommunicationSync.js

@@ -0,0 +1,111 @@
+import { nativeEmail, nativeFingerprint, nativeInteger, nativeJson, nativeStamp, nativeText, nativeTransactions } from "./postgresNativeOperations.js";
+export const nativeSyncEventType = (binding) => `communication.native.sync.${nativeFingerprint(nativeText(binding))}`;
+function nativeSyncRegistration(options, input) {
+    const binding = nativeText(options.binding), provider = nativeText(options.providerKind), eventType = nativeSyncEventType(binding);
+    const email = nativeEmail(input.normalizedEmail), source = nativeText(input.sourceKey), contact = nativeText(input.contactId);
+    if (!["subscribe", "update", "unsubscribe", "suppress"].includes(input.eventType) || !["marketing_launch_offer", "marketing_newsletter"].includes(input.purpose))
+        throw new Error("native_sync_event_invalid");
+    const payload = nativeJson(input.payload ?? {});
+    const refs = [input.originProviderKind ?? null, input.originProviderEventId ?? null, input.remoteProfileId ?? null, input.remoteListId ?? null].map(value => value === null ? null : nativeText(value));
+    const fact = nativeFingerprint(JSON.stringify([provider, contact, email, input.eventType, input.purpose, payload, ...refs]));
+    // Reuse the rail's ordering barrier for successive preferences of one contact/target.
+    const aggregate = nativeFingerprint(JSON.stringify([binding, provider, contact])).slice(0, 32);
+    return async (db) => {
+        // One rail identity for each source event and exact target binding.
+        await db.query(`INSERT INTO public.outbox_events (aggregate_type,aggregate_id,event_type,idempotency_key,payload)
+          VALUES ('communication_native_sync',$4::uuid,$1,$2,$3::jsonb) ON CONFLICT (event_type,idempotency_key) DO NOTHING`, [eventType, source, payload, aggregate]);
+        const work = (await db.query("SELECT id FROM public.outbox_events WHERE event_type=$1 AND idempotency_key=$2 FOR UPDATE", [eventType, source])).rows[0];
+        await db.query(`INSERT INTO public.communication_native_sync_state
+          (work_id,binding,provider_kind,contact_id,normalized_email,purpose,event_kind,origin_provider_kind,origin_provider_event_id,remote_profile_id,remote_list_id,command_fingerprint)
+          VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12) ON CONFLICT (work_id) DO NOTHING`, [work.id, binding, provider, contact, email, input.purpose, input.eventType, ...refs, fact]);
+        const state = (await db.query("SELECT command_fingerprint FROM public.communication_native_sync_state WHERE work_id=$1", [work.id])).rows[0];
+        if (state?.command_fingerprint !== fact)
+            throw new Error("native_sync_registration_conflict");
+        return { id: nativeText(work.id) };
+    };
+}
+/** Trusted host transaction seam; registration validation remains shared with the standalone store. */
+export async function registerNativeSyncWorkInTransaction(db, options, input) {
+    return nativeSyncRegistration(options, input)(db);
+}
+/** No sidecar claim/lease/drainer. Only runCommunicationSyncDispatch executes membership effects. */
+export function createPostgresCommunicationSyncStore(env, options) {
+    const binding = nativeText(options.binding), provider = nativeText(options.providerKind), eventType = nativeSyncEventType(binding);
+    const lane = nativeTransactions(env, options, ["public.communication_native_sync_state", "public.outbox_events", "public.communication_recipient_consents"]);
+    const checkProvider = (value) => { if (value !== provider)
+        throw new Error("native_sync_binding_conflict"); };
+    return {
+        close: lane.close,
+        async registerWork(input) {
+            const register = nativeSyncRegistration(options, input);
+            return lane.run(db => register(db));
+        },
+        registerPreference(input) {
+            const email = nativeEmail(input.email), fingerprint = nativeFingerprint(email), purpose = nativeText(input.purpose);
+            if (!["tester_program", "marketing_launch_offer", "marketing_newsletter"].includes(purpose) || !["denied", "suppressed"].includes(input.state))
+                throw new Error("native_preference_invalid");
+            return lane.run(async (db) => {
+                await db.query("SELECT pg_advisory_xact_lock(hashtextextended($1,0))", [JSON.stringify([fingerprint, purpose])]);
+                const old = (await db.query("SELECT state,updated_at FROM public.communication_recipient_consents WHERE recipient_fingerprint=$1 AND purpose=$2 FOR UPDATE", [fingerprint, purpose])).rows[0];
+                const row = old?.state === input.state ? old : (await db.query(`INSERT INTO public.communication_recipient_consents (recipient_fingerprint,purpose,state)
+          VALUES ($1,$2,$3) ON CONFLICT (recipient_fingerprint,purpose) DO UPDATE SET state=excluded.state,updated_at=clock_timestamp() RETURNING state,updated_at`, [fingerprint, purpose, input.state])).rows[0];
+                let workId = null;
+                if (purpose !== "tester_program") {
+                    const sourceKey = nativeFingerprint(JSON.stringify([fingerprint, purpose, input.state, nativeStamp(row.updated_at)]));
+                    workId = (await registerNativeSyncWorkInTransaction(db, options, { sourceKey, contactId: fingerprint, normalizedEmail: email, eventType: input.state === "suppressed" ? "suppress" : "unsubscribe", purpose: purpose })).id;
+                }
+                return { updated: true, email, purpose: purpose, state: input.state, workId, alreadySuppressed: old?.state === input.state };
+            });
+        },
+        claimBatch(input) {
+            checkProvider(input.providerKind);
+            nativeInteger(input.batchSize, 1, 100);
+            nativeInteger(input.visibilitySeconds, 60, 3600);
+            nativeInteger(input.maxAttempts, 1, 20);
+            return lane.run(async (db) => {
+                const work = await options.rail(db).claimBatch({ eventTypes: [eventType], knownEventTypes: [eventType], batchSize: input.batchSize, visibilitySeconds: input.visibilitySeconds, maxAttempts: input.maxAttempts });
+                const events = [];
+                for (const row of work) {
+                    const state = (await db.query("UPDATE public.communication_native_sync_state SET max_attempts=$4 WHERE work_id=$1 AND binding=$2 AND provider_kind=$3 RETURNING *", [row.id, binding, provider, input.maxAttempts])).rows[0];
+                    if (!state)
+                        throw new Error("native_sync_sidecar_missing");
+                    const payload = (await db.query("SELECT payload FROM public.outbox_events WHERE id=$1", [row.id])).rows[0].payload;
+                    nativeJson(payload);
+                    events.push({ id: nativeText(row.id), claimToken: nativeText(row.metadata.claimToken), contactId: nativeText(state.contact_id), normalizedEmail: nativeEmail(state.normalized_email), eventType: state.event_kind,
+                        purpose: state.purpose, payload: payload, attemptCount: nativeInteger(row.attempts - 1, 0, 19),
+                        originProviderKind: state.origin_provider_kind, originProviderEventId: state.origin_provider_event_id, remoteProfileId: state.remote_profile_id, remoteListId: state.remote_list_id });
+                }
+                return events;
+            });
+        },
+        markSent(input) {
+            checkProvider(input.providerKind);
+            const summary = nativeJson(input.responseSummary ?? {}), remote = input.remoteProfileId == null ? null : nativeText(input.remoteProfileId);
+            return lane.run(async (db) => {
+                const row = (await db.query(`SELECT e.id FROM public.outbox_events e JOIN public.communication_native_sync_state s ON s.work_id=e.id
+          WHERE e.id=$1 AND s.binding=$2 AND s.provider_kind=$3 AND e.event_type=$4 AND e.status='processing' AND e.metadata->>'claimToken'=$5 FOR UPDATE OF e,s`, [input.eventId, binding, provider, eventType, input.claimToken])).rows[0];
+                if (!row)
+                    return false;
+                if (!(await options.rail(db).markProcessed({ eventId: input.eventId, claimToken: input.claimToken })).applied)
+                    throw new Error("native_sync_ack_lost");
+                await db.query("UPDATE public.communication_native_sync_state SET remote_profile_id=$2,response_summary=$3::jsonb WHERE work_id=$1", [input.eventId, remote, summary]);
+                return true;
+            });
+        },
+        markFailed(input) {
+            checkProvider(input.providerKind);
+            nativeInteger(input.backoffSeconds, 0, 86400);
+            return lane.run(async (db) => {
+                const row = (await db.query(`SELECT s.max_attempts FROM public.outbox_events e JOIN public.communication_native_sync_state s ON s.work_id=e.id
+          WHERE e.id=$1 AND s.binding=$2 AND s.provider_kind=$3 AND e.event_type=$4 AND e.status='processing' AND e.metadata->>'claimToken'=$5 FOR UPDATE OF e,s`, [input.eventId, binding, provider, eventType, input.claimToken])).rows[0];
+                if (!row)
+                    return false;
+                const result = await options.rail(db).markFailed({ eventId: input.eventId, claimToken: input.claimToken, error: nativeText(input.error, 2000), outcome: input.retry ? "retry" : "discard", baseDelaySeconds: input.backoffSeconds, maxDelaySeconds: input.backoffSeconds, maxAttempts: nativeInteger(Number(row.max_attempts), 1, 20), snoozeSeconds: 300 });
+                if (!["failed", "discarded"].includes(result.status))
+                    throw new Error("native_sync_ack_lost");
+                await db.query("UPDATE public.communication_native_sync_state SET response_summary=$2::jsonb WHERE work_id=$1", [input.eventId, JSON.stringify({ status: result.status })]);
+                return true;
+            });
+        },
+    };
+}

package/dist/communications/postgresConsentEvaluator.d.ts

@@ -0,0 +1,19 @@
+import type { PostgresDataGatewayEnv, PostgresDataGatewayOptions } from "../data/index.js";
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { type NativeConsentDecision, type NativeConsentInput } from "./nativeOperations.js";
+export interface NativeConsentOptions extends PostgresDataGatewayOptions {
+    registry?: CommunicationPurposeRegistry<string>;
+    /** Host-owned authoritative tester pause, read in the decision transaction. Missing means unpaused. */
+    testerPaused?: (db: import("../data/index.js").PgQueryExecutor, input: NativeConsentInput) => Promise<boolean>;
+}
+export interface NativeConsentEvaluator {
+    evaluate(input: NativeConsentInput): Promise<NativeConsentDecision>;
+    close(): Promise<void>;
+    readonly guarantees: {
+        readonly managedFrequencyCaps: false;
+        readonly legacyContactTouching: false;
+        readonly sendTimeFence: false;
+    };
+}
+/** Bounded P4 policy, authoritative native permission and durable decision. Evaluation never sends. */
+export declare function createPostgresConsentEvaluator(env: PostgresDataGatewayEnv, options?: NativeConsentOptions): NativeConsentEvaluator;

package/dist/communications/postgresConsentEvaluator.js

@@ -0,0 +1,43 @@
+import { evaluateCommunicationPolicy } from "./consentPolicy.js";
+import { defaultCommunicationPurposeRegistry } from "./consentPurposeRegistry.js";
+import { NativeConsentEvaluationUnavailableError } from "./nativeOperations.js";
+import { nativeEmail, nativeFingerprint, nativeText, nativeTransactions } from "./postgresNativeOperations.js";
+/** Bounded P4 policy, authoritative native permission and durable decision. Evaluation never sends. */
+export function createPostgresConsentEvaluator(env, options = {}) {
+    const lane = nativeTransactions(env, options, ["public.communication_native_policy_decisions", "public.communication_recipient_consents", "public.notification_recipients"]);
+    const registry = options.registry ?? defaultCommunicationPurposeRegistry;
+    return {
+        close: lane.close,
+        guarantees: { managedFrequencyCaps: false, legacyContactTouching: false, sendTimeFence: false },
+        async evaluate(input) {
+            try {
+                const email = nativeEmail(input.email), fingerprint = nativeFingerprint(email), purpose = nativeText(input.purpose);
+                const recipientKind = input.recipientKind ?? "external_contact";
+                if (!["external_contact", "tester", "customer", "lead", "admin_internal"].includes(recipientKind))
+                    throw new Error("native_recipient_kind_invalid");
+                return await lane.run(async (db) => {
+                    const permission = (await db.query("SELECT state,captured_at,updated_at FROM public.communication_recipient_consents WHERE recipient_fingerprint=$1 AND purpose=$2 FOR SHARE", [fingerprint, purpose])).rows[0];
+                    if (permission && !["granted", "denied", "suppressed"].includes(String(permission.state)))
+                        throw new Error("native_permission_invalid");
+                    const paused = purpose === "tester_program" && options.testerPaused ? await options.testerPaused(db, input) : false;
+                    if (typeof paused !== "boolean")
+                        throw new Error("native_pause_invalid");
+                    let result = evaluateCommunicationPolicy({ purpose, recipientKind, permission: { state: permission ? permission.state : null, legacySequencePaused: paused } }, registry);
+                    let activeRecipient = null;
+                    if (purpose === "admin_notification") {
+                        const rows = (await db.query("SELECT active FROM public.notification_recipients WHERE id=$1 AND email=$2 FOR SHARE", [input.sourceTable === "notification_recipients" ? input.sourceId ?? null : null, email])).rows;
+                        activeRecipient = rows.length === 1 && rows[0].active === true;
+                        if (!activeRecipient)
+                            result = { decision: "blocked", reason: "notification_recipient_inactive" };
+                    }
+                    const row = (await db.query(`INSERT INTO public.communication_native_policy_decisions (recipient_fingerprint,purpose,allowed,reason,permission_snapshot,source_table,source_id)
+            VALUES ($1,$2,$3,$4,$5::jsonb,$6,$7) RETURNING id`, [fingerprint, purpose, result.decision === "allowed", result.reason, JSON.stringify({ permission: permission ?? null, legacySequencePaused: paused, activeRecipient, recipientKind }), input.sourceTable ?? null, input.sourceId ?? null])).rows[0];
+                    return { allowed: result.decision === "allowed", reason: result.reason, decisionId: nativeText(row?.id) };
+                });
+            }
+            catch (error) {
+                throw new NativeConsentEvaluationUnavailableError(error);
+            }
+        },
+    };
+}

package/dist/communications/postgresDeliveryReconciliation.d.ts

@@ -0,0 +1,3 @@
+import type { PostgresDataGatewayEnv } from "../data/index.js";
+import type { NativeCommunicationsOptions, NativeDeliveryStore } from "./nativeOperations.js";
+export declare function createPostgresDeliveryReconciliationPort(env: PostgresDataGatewayEnv, options: NativeCommunicationsOptions): NativeDeliveryStore;

package/dist/communications/postgresDeliveryReconciliation.js

@@ -0,0 +1,113 @@
+import { nativeEmail, nativeFingerprint, nativeInteger, nativeStamp, nativeText, nativeTime, nativeTransactions } from "./postgresNativeOperations.js";
+const kinds = ["sent", "delayed", "delivered", "failed", "bounced", "complained"];
+// Terminal/suppression precedence is monotonic; event chronology remains in the fact log.
+const rank = (kind) => kind === null ? -1 : kinds.indexOf(kind);
+export function createPostgresDeliveryReconciliationPort(env, options) {
+    const binding = nativeText(options.binding);
+    const lane = nativeTransactions(env, options, ["public.communication_native_sends", "public.communication_native_observations", "public.communication_recipient_consents"]);
+    const store = {
+        close: lane.close,
+        async registerNetworkTarget(input) {
+            if (input.evidence !== "network_accepted" || input.messageId.startsWith("captured:"))
+                throw new Error("native_network_acceptance_required");
+            const values = [binding, nativeText(input.sourceKey), nativeText(input.messageId), nativeFingerprint(nativeEmail(input.recipientEmail)), nativeText(input.templateReference), nativeTime(input.acceptedAt)];
+            return lane.run(async (db) => {
+                await db.query(`INSERT INTO public.communication_native_sends (binding,source_key,message_id,recipient_fingerprint,template_reference,accepted_at)
+          VALUES ($1,$2,$3,$4,$5,$6) ON CONFLICT (binding,source_key) DO NOTHING`, values);
+                const row = (await db.query(`SELECT * FROM public.communication_native_sends WHERE binding=$1 AND source_key=$2 FOR UPDATE`, values.slice(0, 2))).rows[0];
+                if (!row || row.message_id !== values[2] || row.recipient_fingerprint !== values[3] || row.template_reference !== values[4] || nativeStamp(row.accepted_at) !== values[5])
+                    throw new Error("native_send_registration_conflict");
+                return { id: nativeText(row.id) };
+            });
+        },
+        findFrozenSends(input) {
+            const now = nativeTime(input.now), limit = nativeInteger(input.limit, 1, 100), grace = nativeInteger(input.graceMinutes, 0, 10080);
+            return lane.run(async (db) => (await db.query(`SELECT id,message_id FROM public.communication_native_sends
+        WHERE binding=$1 AND abandoned_at IS NULL AND (observed_state IS NULL OR observed_state IN ('sent','delayed'))
+        AND accepted_at <= $2::timestamptz - make_interval(mins => $3) ORDER BY last_poll_at NULLS FIRST, accepted_at,id LIMIT $4`, [binding, now, grace, limit])).rows.map(row => ({ id: nativeText(row.id), messageId: nativeText(row.message_id) })));
+        },
+        async applyObservation(input) {
+            const kind = input.kind;
+            if (!kinds.includes(kind) || !["poll", "callback"].includes(input.source))
+                throw new Error("native_observation_invalid");
+            const at = nativeTime(input.occurredAt), key = nativeText(input.observationKey), message = nativeText(input.messageId);
+            const fingerprint = input.recipientEmail === null ? null : nativeFingerprint(nativeEmail(input.recipientEmail));
+            await lane.run(async (db) => {
+                const send = (await db.query("SELECT * FROM public.communication_native_sends WHERE id=$1 AND binding=$2 FOR UPDATE", [input.sendId, binding])).rows[0];
+                if (!send || send.message_id !== message || (fingerprint !== null && send.recipient_fingerprint !== fingerprint))
+                    throw new Error("native_observation_identity_conflict");
+                const fact = nativeFingerprint(JSON.stringify([input.sendId, message, kind, at, send.recipient_fingerprint]));
+                const inserted = await db.query(`INSERT INTO public.communication_native_observations (binding,observation_key,send_id,kind,occurred_at,source,fact_fingerprint)
+          VALUES ($1,$2,$3,$4,$5,$6,$7) ON CONFLICT (binding,observation_key) DO NOTHING RETURNING observation_key`, [binding, key, input.sendId, kind, at, input.source, fact]);
+                if (!inserted.rows.length) {
+                    const old = (await db.query("SELECT fact_fingerprint FROM public.communication_native_observations WHERE binding=$1 AND observation_key=$2", [binding, key])).rows[0];
+                    if (old?.fact_fingerprint !== fact)
+                        throw new Error("native_observation_replay_conflict");
+                    return;
+                }
+                if (rank(kind) > rank(send.observed_state) || (kind === send.observed_state && at > nativeStamp(send.observed_at))) {
+                    await db.query("UPDATE public.communication_native_sends SET observed_state=$3,observed_at=$4 WHERE id=$1 AND binding=$2", [input.sendId, binding, kind, at]);
+                }
+                if (kind === "bounced" || kind === "complained") {
+                    for (const purpose of ["marketing_launch_offer", "marketing_newsletter", "tester_program"])
+                        await db.query(`INSERT INTO public.communication_recipient_consents (recipient_fingerprint,purpose,state,captured_at,updated_at)
+            VALUES ($1,$2,'suppressed',$3,$3) ON CONFLICT (recipient_fingerprint,purpose) DO UPDATE SET state='suppressed',updated_at=greatest(communication_recipient_consents.updated_at,excluded.updated_at)`, [send.recipient_fingerprint, purpose, at]);
+                }
+            });
+        },
+        applyPolledEvent(input) {
+            return store.applyObservation({ sendId: input.sendId, messageId: input.messageId, observationKey: nativeFingerprint(JSON.stringify([input.sendId, input.eventType, nativeTime(input.eventAt)])), kind: input.eventType, occurredAt: input.eventAt, recipientEmail: input.recipientEmail, source: "poll" });
+        },
+        async recordPollAttempt(input) {
+            await lane.run(async (db) => {
+                const result = await db.query("UPDATE public.communication_native_sends SET last_poll_at=greatest(last_poll_at,$3::timestamptz),not_found_count=0 WHERE id=$1 AND binding=$2 RETURNING id", [input.sendId, binding, nativeTime(input.attemptedAt)]);
+                if (!result.rows.length)
+                    throw new Error("native_send_not_found");
+            });
+        },
+        recordSendNotFound(input) {
+            nativeInteger(input.threshold, 1, 100);
+            return lane.run(async (db) => {
+                const send = (await db.query("SELECT abandoned_at FROM public.communication_native_sends WHERE id=$1 AND binding=$2 FOR UPDATE", [input.sendId, binding])).rows[0];
+                if (!send)
+                    throw new Error("native_send_not_found");
+                const result = (await db.query(`UPDATE public.communication_native_sends SET not_found_count=least(not_found_count,2147483646)+1,last_poll_at=clock_timestamp(),
+          abandoned_at=CASE WHEN not_found_count >= $3-1 THEN coalesce(abandoned_at,clock_timestamp()) ELSE abandoned_at END WHERE id=$1 AND binding=$2 RETURNING abandoned_at`, [input.sendId, binding, input.threshold])).rows[0];
+                return { abandoned: send.abandoned_at === null && result.abandoned_at !== null };
+            });
+        },
+        findByMessageId(messageId) {
+            const message = nativeText(messageId);
+            return lane.run(async (db) => {
+                const rows = (await db.query("SELECT id FROM public.communication_native_sends WHERE binding=$1 AND message_id=$2", [binding, message])).rows;
+                if (rows.length > 1)
+                    throw new Error("native_message_identity_ambiguous");
+                return rows.length ? { id: nativeText(rows[0].id) } : null;
+            });
+        },
+        async listEvidence(input) {
+            const limit = nativeInteger(input.limit, 1, 100);
+            const ids = await lane.run(async (db) => (await db.query("SELECT id FROM public.communication_native_sends WHERE binding=$1 ORDER BY accepted_at DESC,id DESC LIMIT $2", [binding, limit])).rows.map(row => nativeText(row.id)));
+            const evidence = [];
+            for (const id of ids) {
+                const row = await store.readEvidence(id);
+                if (row)
+                    evidence.push(row);
+            }
+            return evidence;
+        },
+        readEvidence(id) {
+            return lane.run(async (db) => {
+                const row = (await db.query("SELECT * FROM public.communication_native_sends WHERE id=$1 AND binding=$2", [id, binding])).rows[0];
+                if (!row)
+                    return null;
+                const observations = (await db.query("SELECT observation_key,kind,occurred_at,source FROM public.communication_native_observations WHERE send_id=$1 AND binding=$2 ORDER BY occurred_at,observation_key", [id, binding])).rows;
+                return { id: nativeText(row.id), sourceKey: nativeText(row.source_key), messageId: nativeText(row.message_id), acceptedAt: nativeStamp(row.accepted_at),
+                    observedState: row.observed_state, observedAt: row.observed_at === null ? null : nativeStamp(row.observed_at),
+                    lastPollAt: row.last_poll_at === null ? null : nativeStamp(row.last_poll_at), notFoundCount: nativeInteger(Number(row.not_found_count), 0, 2147483647), abandonedAt: row.abandoned_at === null ? null : nativeStamp(row.abandoned_at),
+                    observations: observations.map(fact => ({ key: nativeText(fact.observation_key), kind: fact.kind, occurredAt: nativeStamp(fact.occurred_at), source: fact.source })) };
+            });
+        },
+    };
+    return store;
+}

package/dist/communications/postgresNativeOperations.d.ts

@@ -0,0 +1,13 @@
+import { type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+export declare const nativeFingerprint: (value: string) => string;
+export declare function nativeText(value: unknown, max?: number): string;
+export declare function nativeEmail(value: unknown): string;
+export declare function nativeTime(value: unknown): string;
+export declare function nativeInteger(value: number, min: number, max: number): number;
+export declare function nativeJson(value: unknown): string;
+export declare const nativeStamp: (value: unknown) => string;
+/** Private capability-local helper. The host owns the connection authority; no SET ROLE or runtime DDL. */
+export declare function nativeTransactions(env: PostgresDataGatewayEnv, options: PostgresDataGatewayOptions, tables: string[]): {
+    close: () => Promise<void>;
+    run: <T>(work: (db: PgQueryExecutor) => Promise<T>) => Promise<T>;
+};

package/dist/communications/postgresNativeOperations.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { createPostgresRoleFreeTransactionLane } from "../data/index.js";
+export const nativeFingerprint = (value) => createHash("sha256").update(value).digest("hex");
+export function nativeText(value, max = 256) {
+    if (typeof value !== "string" || !value.trim() || value.length > max || [...value].some(character => character.codePointAt(0) < 32 || character.codePointAt(0) === 127))
+        throw new Error("native_communications_text_invalid");
+    return value;
+}
+export function nativeEmail(value) {
+    const email = nativeText(value, 320).trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+        throw new Error("native_communications_email_invalid");
+    return email;
+}
+export function nativeTime(value) {
+    const parts = typeof value === "string" ? /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.(\d{1,6}))?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(value) : null;
+    if (!parts || typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        throw new Error("native_communications_time_invalid");
+    if (new Date(value.slice(0, 10) + "T00:00:00Z").toISOString().slice(0, 10) !== value.slice(0, 10))
+        throw new Error("native_communications_time_invalid");
+    // PostgreSQL stores microseconds. Never collapse two distinct immutable facts to JS milliseconds.
+    return new Date(value).toISOString().replace(/\.\d{3}Z$/, `.${(parts[1] ?? "").padEnd(6, "0")}Z`);
+}
+export function nativeInteger(value, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new Error("native_communications_bound_invalid");
+    return value;
+}
+export function nativeJson(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("native_communications_object_invalid");
+    const text = JSON.stringify(value);
+    if (text.length > 4096)
+        throw new Error("native_communications_object_too_large");
+    return text;
+}
+export const nativeStamp = (value) => nativeTime(value instanceof Date ? value.toISOString() : value);
+/** Private capability-local helper. The host owns the connection authority; no SET ROLE or runtime DDL. */
+export function nativeTransactions(env, options, tables) {
+    if (!env.connectionString.trim())
+        throw new Error("communications_database_url_required");
+    const lane = createPostgresRoleFreeTransactionLane(env, options);
+    return {
+        close: lane.close,
+        run: (work) => lane.run(async (gateway) => {
+            const db = gateway;
+            // Effective privileges include PUBLIC, role membership and column/default grants.
+            // Missing relations, malformed responses and untrusted execution roles all refuse.
+            const row = (await db.query(`SELECT current_user IN ('anon','authenticated','authenticator') AS browser,
+        EXISTS (SELECT 1 FROM unnest($1::text[]) t(name), pg_roles r
+          WHERE r.rolname IN ('anon','authenticated','authenticator') AND
+          (has_table_privilege(r.oid, t.name, 'SELECT,INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER')
+          OR has_any_column_privilege(r.oid, t.name, 'SELECT,INSERT,UPDATE,REFERENCES')))
+        OR EXISTS (SELECT 1 FROM unnest($1::text[]) t(name), pg_class c,
+          LATERAL aclexplode(coalesce(c.relacl, acldefault('r',c.relowner))) a WHERE c.oid = t.name::regclass AND a.grantee = 0)
+        OR EXISTS (SELECT 1 FROM unnest($1::text[]) t(name), pg_attribute c,
+          LATERAL aclexplode(c.attacl) a WHERE c.attrelid = t.name::regclass AND a.grantee = 0) AS unsafe`, [tables])).rows[0];
+            if (row?.browser !== false || row?.unsafe !== false)
+                throw new Error("native_communications_privileges_unsafe");
+            return work(db);
+        }),
+    };
+}

package/dist/communications/postgresNotificationRecipients.d.ts

@@ -0,0 +1,37 @@
+import type { PostgresDataGatewayEnv, PostgresDataGatewayOptions } from "../data/index.js";
+import type { NativeNotificationRecipient, NativeNotificationType } from "./nativeOperations.js";
+export interface NativeNotificationRecipientsOptions extends PostgresDataGatewayOptions {
+    operatorId: string;
+}
+export interface NativeNotificationRecipientsPort {
+    listNotificationRecipients(input: {
+        notification_type: NativeNotificationType;
+    }): Promise<{
+        recipients: NativeNotificationRecipient[];
+    }>;
+    createNotificationRecipient(input: {
+        email: string;
+        name: string | null;
+        notification_type: NativeNotificationType;
+        active: true;
+    }): Promise<{
+        created: true;
+        email: string;
+        notification_type: NativeNotificationType;
+    }>;
+    updateNotificationRecipient(input: {
+        recipientId: string;
+        active: boolean;
+    }): Promise<{
+        updated: true;
+        recipientId: string;
+    }>;
+    deleteNotificationRecipient(input: {
+        recipientId: string;
+    }): Promise<{
+        deleted: true;
+        recipientId: string;
+    }>;
+    close(): Promise<void>;
+}
+export declare function createPostgresNotificationRecipientsPort(env: PostgresDataGatewayEnv, options: NativeNotificationRecipientsOptions): NativeNotificationRecipientsPort;