@openlup/platform 0.16.0 → 0.17.0

package/src/communications/newsletterIntegrationContracts.ts

@@ -0,0 +1,154 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { z } from "./validation.js";
+
+export const NEWSLETTER_MARKETING_PURPOSES = [
+  "marketing_launch_offer",
+  "marketing_newsletter",
+] as const;
+
+export const NEWSLETTER_SYNC_EVENT_TYPES = [
+  "subscribe",
+  "update",
+  "unsubscribe",
+  "suppress",
+] as const;
+
+export const NEWSLETTER_WEBHOOK_EVENT_TYPES = [
+  ...NEWSLETTER_SYNC_EVENT_TYPES,
+  "complaint",
+  "bounce",
+  "email_change",
+  "profile_update",
+  "ignored",
+] as const;
+
+export const NEWSLETTER_PROVIDER_CAPABILITY_KEYS = [
+  "subscribe",
+  "unsubscribe",
+  "suppress",
+  "unsuppress",
+  "doubleOptIn",
+  "emailChange",
+  "listMembership",
+  "webhookIdempotency",
+  "retryAfter",
+] as const;
+
+import type { NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NewsletterProviderKind, NewsletterSyncEventType, NewsletterWebhookEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent, NewsletterSyncEvent } from "./contracts/newsletter.js";
+export type { NewsletterProviderKind, NewsletterMarketingPurpose, NewsletterSyncEventType, NewsletterWebhookEventType, NewsletterProviderCapabilityKey, NewsletterProviderCapabilities, NewsletterWebhookEvent, NewsletterSyncEvent } from "./contracts/newsletter.js";
+export const defaultNewsletterProviderCapabilities: NewsletterProviderCapabilities = {
+  subscribe: false,
+  unsubscribe: false,
+  suppress: false,
+  unsuppress: false,
+  doubleOptIn: false,
+  emailChange: false,
+  listMembership: false,
+  webhookIdempotency: false,
+  retryAfter: false,
+};
+
+export const fullNewsletterProviderCapabilities: NewsletterProviderCapabilities = {
+  subscribe: true,
+  unsubscribe: true,
+  suppress: true,
+  unsuppress: true,
+  doubleOptIn: true,
+  emailChange: true,
+  listMembership: true,
+  webhookIdempotency: true,
+  retryAfter: true,
+};
+
+export const newsletterProviderKindSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9_-]*$/);
+
+export const newsletterMarketingPurposeSchema = z.enum(NEWSLETTER_MARKETING_PURPOSES);
+export const newsletterSyncEventTypeSchema = z.enum(NEWSLETTER_SYNC_EVENT_TYPES);
+export const newsletterWebhookEventTypeSchema = z.enum(NEWSLETTER_WEBHOOK_EVENT_TYPES);
+
+export const newsletterProviderCapabilitiesSchema = z.object({
+  subscribe: z.boolean(),
+  unsubscribe: z.boolean(),
+  suppress: z.boolean(),
+  unsuppress: z.boolean(),
+  doubleOptIn: z.boolean(),
+  emailChange: z.boolean(),
+  listMembership: z.boolean(),
+  webhookIdempotency: z.boolean(),
+  retryAfter: z.boolean(),
+});
+
+export const canonicalNewsletterWebhookEventSchema = z.object({
+  providerKind: newsletterProviderKindSchema,
+  providerEventId: z.string().trim().min(1).max(200),
+  eventType: newsletterWebhookEventTypeSchema,
+  email: z.string().trim().email().nullable().optional(),
+  remoteProfileId: z.string().trim().min(1).max(200).nullable().optional(),
+  remoteListId: z.string().trim().min(1).max(200).nullable().optional(),
+  purpose: newsletterMarketingPurposeSchema.nullable().optional(),
+  explicitOptInEvidence: z.boolean().optional(),
+  doubleOptInStatus: z.enum(["confirmed", "pending", "unknown"]).optional(),
+  occurredAt: z.string().datetime({ offset: true }).nullable().optional(),
+  payload: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type CanonicalNewsletterWebhookEvent = z.infer<
+  typeof canonicalNewsletterWebhookEventSchema
+>;
+
+export function normalizeCanonicalNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(
+  event: Omit<CanonicalNewsletterWebhookEvent, "purpose"> & { purpose?: Purpose | null },
+): NewsletterWebhookEvent<Purpose> {
+  return {
+    providerKind: event.providerKind,
+    providerEventId: event.providerEventId,
+    eventType: event.eventType,
+    email: event.email ?? null,
+    remoteProfileId: event.remoteProfileId ?? null,
+    remoteListId: event.remoteListId ?? null,
+    purpose: event.purpose ?? null,
+    explicitOptInEvidence: event.explicitOptInEvidence === true,
+    doubleOptInStatus: event.doubleOptInStatus ?? "unknown",
+    occurredAt: event.occurredAt ?? null,
+    rawPayload: event.payload ?? {},
+  };
+}
+
+export function requiredNewsletterCapabilityForEvent(
+  eventType: NewsletterSyncEventType,
+): NewsletterProviderCapabilityKey {
+  if (eventType === "subscribe") return "subscribe";
+  if (eventType === "unsubscribe") return "unsubscribe";
+  if (eventType === "suppress") return "suppress";
+  return "listMembership";
+}
+
+export function supportsNewsletterSyncEvent(
+  capabilities: NewsletterProviderCapabilities,
+  eventType: NewsletterSyncEventType,
+): boolean {
+  return capabilities[requiredNewsletterCapabilityForEvent(eventType)] === true;
+}
+
+/** Explicit registry binding; legacy schemas above retain their two-purpose default. */
+export function createNewsletterIntegrationSchemas<Purpose extends string>(registry: CommunicationPurposeRegistry<Purpose>) {
+  const purpose = z.custom<Purpose>((value) => registry.has(value), "unregistered_communication_purpose");
+  return {
+    purpose,
+    webhookEvent: canonicalNewsletterWebhookEventSchema.extend({ purpose: purpose.nullable().optional() }),
+    syncEvent: z.object({
+      id: z.string().min(1), claimToken: z.string().min(1), contactId: z.string().min(1),
+      normalizedEmail: z.string().email(), eventType: newsletterSyncEventTypeSchema,
+      purpose, payload: z.record(z.string(), z.unknown()), attemptCount: z.number().int().min(0),
+      originProviderKind: newsletterProviderKindSchema.nullable().optional(),
+      originProviderEventId: z.string().nullable().optional(), remoteProfileId: z.string().nullable().optional(),
+      remoteListId: z.string().nullable().optional(),
+    }),
+  };
+}

package/src/communications/newsletterWebhookPort.ts

@@ -0,0 +1,104 @@
+import type {
+  NewsletterWebhookPort,
+  NormalizedNewsletterWebhookEvent,
+} from "./contracts/newsletterWebhook.js";
+
+export interface NewsletterWebhookRpcClient {
+  rpc(
+    functionName: string,
+    args: Record<string, unknown>,
+  ): PromiseLike<{ data: unknown; error: { code?: string; message?: string } | null }>;
+}
+
+export function createSupabaseNewsletterWebhookPort(
+  client: NewsletterWebhookRpcClient,
+): NewsletterWebhookPort {
+  return {
+    async recordProviderEvent(input) {
+      const { data, error } = await client.rpc("communication_record_provider_event", {
+        p_provider_kind: input.providerKind,
+        p_provider_event_id: input.providerEventId,
+        p_event_type: input.eventType,
+        p_email: input.email,
+        p_remote_profile_id: input.remoteProfileId,
+        p_purpose: input.purpose,
+        p_state: input.state,
+        p_payload: sanitizePayload(input.rawPayload),
+        p_metadata: providerEventMetadata(input),
+        p_processing_status: input.processingStatus,
+      });
+      if (error) throw rpcFailure("communication_record_provider_event", error);
+      const record = isRecord(data) ? data : {};
+      return {
+        providerEventId: readString(record.providerEventId) ?? "",
+        contactId: readString(record.contactId),
+        inserted: record.inserted === true,
+      };
+    },
+
+    async recordPermission(input) {
+      const { error } = await client.rpc("communication_record_permission_event", {
+        p_contact_id: input.contactId,
+        p_purpose: input.purpose,
+        p_state: input.state,
+        p_source: "newsletter_provider_webhook",
+        p_source_ref: {
+          providerKind: input.providerKind,
+          providerEventId: input.providerEventId,
+        },
+        p_reason: input.reason,
+        p_metadata: {
+          ...input.metadata,
+          actorType: "provider_webhook",
+          captureMethod: "newsletter_webhook",
+          originProviderKind: input.providerKind,
+          originProviderEventId: input.providerEventId,
+        },
+        p_captured_at: new Date().toISOString(),
+        p_create_sync_event: true,
+      });
+      if (error) throw rpcFailure("communication_record_permission_event", error);
+    },
+
+    async markProviderEvent(input) {
+      const { error } = await client.rpc("communication_mark_provider_event_processed", {
+        p_provider_event_id: input.providerEventId,
+        p_processing_status: input.status,
+        p_metadata: input.metadata,
+      });
+      if (error) throw rpcFailure("communication_mark_provider_event_processed", error);
+    },
+  };
+}
+
+function providerEventMetadata(
+  input: NormalizedNewsletterWebhookEvent & { processingStatus: "received" | "ignored" },
+): Record<string, unknown> {
+  return {
+    occurredAt: input.occurredAt,
+    explicitOptInEvidence: input.explicitOptInEvidence,
+    doubleOptInStatus: input.doubleOptInStatus,
+    remoteListId: input.remoteListId,
+    processingStatus: input.processingStatus,
+  };
+}
+
+function sanitizePayload(payload: Record<string, unknown>): Record<string, unknown> {
+  const sanitized = { ...payload };
+  delete sanitized.apiKey;
+  delete sanitized.token;
+  delete sanitized.secret;
+  return sanitized;
+}
+
+function rpcFailure(rpcName: string, error: { code?: string; message?: string }): Error {
+  return new Error(`${rpcName}_failed: ${error.message ?? error.code ?? "unknown"}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/communications/newsletterWebhookProcessing.ts

@@ -0,0 +1,102 @@
+import type { NewsletterMarketingPurpose, NewsletterWebhookEvent } from "./contracts/newsletter.js";
+import type { NewsletterWebhookPort } from "./contracts/newsletterWebhook.js";
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+
+export interface NewsletterWebhookProcessResult {
+  provider: string;
+  providerEventId: string;
+  replayed?: boolean;
+  status?: "processed" | "ignored";
+  reason?: string;
+  localState?: "granted" | "suppressed";
+}
+
+const MARKETING_PURPOSES = ["marketing_launch_offer", "marketing_newsletter"] as const;
+
+export async function processNewsletterWebhookEvent<Purpose extends string = NewsletterMarketingPurpose>(input: {
+  providerKind: string;
+  event: NewsletterWebhookEvent<Purpose>;
+  port: NewsletterWebhookPort<Purpose | NewsletterMarketingPurpose>;
+  registry?: CommunicationPurposeRegistry<Purpose>;
+}): Promise<NewsletterWebhookProcessResult> {
+  const { providerKind, event, port } = input;
+  if (input.registry && event.purpose !== null && !input.registry.has(event.purpose)) {
+    throw new Error("unregistered_communication_purpose");
+  }
+  const action = localAction(event);
+  const providerEvent = await port.recordProviderEvent({
+    ...event,
+    state: action.state,
+    processingStatus: action.kind === "ignore" ? "ignored" : "received",
+  });
+
+  if (!providerEvent.inserted) {
+    return { provider: providerKind, providerEventId: event.providerEventId, replayed: true };
+  }
+
+  if (action.kind === "ignore" || !providerEvent.contactId) {
+    await port.markProviderEvent({
+      providerEventId: providerEvent.providerEventId,
+      status: "ignored",
+      metadata: { reason: action.reason },
+    });
+    return {
+      provider: providerKind,
+      providerEventId: event.providerEventId,
+      status: "ignored",
+      reason: action.reason,
+    };
+  }
+
+  for (const purpose of event.purpose ? [event.purpose] : MARKETING_PURPOSES) {
+    await port.recordPermission({
+      contactId: providerEvent.contactId,
+      providerKind,
+      providerEventId: event.providerEventId,
+      purpose,
+      state: action.state,
+      reason: action.reason,
+      metadata: {
+        source: "newsletter_provider_webhook",
+        providerKind,
+        providerEventId: event.providerEventId,
+        remoteProfileId: event.remoteProfileId,
+        remoteListId: event.remoteListId,
+        doubleOptInStatus: event.doubleOptInStatus,
+        explicitOptInEvidence: event.explicitOptInEvidence,
+      },
+    });
+  }
+
+  await port.markProviderEvent({
+    providerEventId: providerEvent.providerEventId,
+    status: "processed",
+    metadata: { localState: action.state, reason: action.reason },
+  });
+
+  return {
+    provider: providerKind,
+    providerEventId: event.providerEventId,
+    status: "processed",
+    localState: action.state,
+  };
+}
+
+function localAction<Purpose extends string>(
+  event: NewsletterWebhookEvent<Purpose>,
+): { kind: "apply"; state: "granted" | "suppressed"; reason: string } | {
+  kind: "ignore";
+  state: null;
+  reason: string;
+} {
+  if (["unsubscribe", "suppress", "complaint"].includes(event.eventType)) {
+    return { kind: "apply", state: "suppressed", reason: `provider_${event.eventType}` };
+  }
+  if (event.eventType === "subscribe") {
+    if (event.explicitOptInEvidence || event.doubleOptInStatus === "confirmed") {
+      return { kind: "apply", state: "granted", reason: "provider_verified_opt_in" };
+    }
+    return { kind: "ignore", state: null, reason: "provider_subscribe_without_verified_opt_in" };
+  }
+  return { kind: "ignore", state: null, reason: "provider_event_not_permission_mutating" };
+}

package/src/communications/originPolicy.ts

@@ -0,0 +1,151 @@
+export type EmailOriginSource = "explicit" | "default";
+export type EmailEnvironment =
+  | "hidden_preview"
+  | "preview"
+  | "staging"
+  | "production"
+  | "production_or_default"
+  | "unknown";
+export type EmailOriginPolicyError =
+  | "hidden_preview_origin_required"
+  | "hidden_preview_origin_must_not_be_production"
+  | "invalid_email_origin";
+
+export interface ResolvedEmailOrigin {
+  origin: string;
+  source: EmailOriginSource;
+  environment: EmailEnvironment;
+  production: boolean;
+}
+
+export type EmailOriginResolution =
+  | { ok: true; origin: string; source: EmailOriginSource; resolved: ResolvedEmailOrigin }
+  | { ok: false; error: EmailOriginPolicyError };
+
+export interface EmailOriginInput {
+  /** Brand/configured default origin used when no explicit origin is set. */
+  defaultOrigin: string;
+  /** Hosts treated as production by the policy (brand-supplied). */
+  productionEmailHosts: string[];
+  explicitBaseUrl?: string | null;
+  customerAuthRedirectOrigin?: string | null;
+  siteUrl?: string | null;
+  hiddenPreviewEnabled?: boolean;
+  environment?: string | null;
+}
+
+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";
+
+export interface EmailOriginConfiguration {
+  defaultOrigin: string;
+  productionEmailHosts: string[];
+}
+
+function clean(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolveEnvironment(input: EmailOriginInput): EmailEnvironment {
+  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: string): string | null {
+  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: string, productionHosts: string[]): boolean {
+  try {
+    return productionHosts.includes(new URL(origin).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function readEmailOriginConfiguration(
+  env: Record<string, string | undefined>,
+  fallback: EmailOriginConfiguration,
+): EmailOriginConfiguration {
+  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: EmailEnvironment): boolean {
+  return environment === "hidden_preview" || environment === "preview" || environment === "staging";
+}
+
+export function resolveEmailOrigin(input: EmailOriginInput): EmailOriginResolution {
+  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/src/communications/postgresCommunicationSync.ts

@@ -0,0 +1,127 @@
+import type { SqlExecutor } from "@openlup/core/readiness";
+import type { PostgresDataGatewayEnv } from "../data/index.js";
+import type { CommunicationSyncStore } from "./communicationSyncWorker.js";
+import type { NewsletterSyncEvent, NewsletterSyncEventType, NewsletterMarketingPurpose } from "./contracts/newsletter.js";
+import type { NativeCommunicationsOptions } from "./nativeOperations.js";
+import { nativeEmail, nativeFingerprint, nativeInteger, nativeJson, nativeStamp, nativeText, nativeTransactions } from "./postgresNativeOperations.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 const nativeSyncEventType = (binding: string): string => `communication.native.sync.${nativeFingerprint(nativeText(binding))}`;
+function nativeSyncRegistration(options: Pick<NativeSyncOptions,"binding"|"providerKind">, input: NativeSyncRegistration): (db: SqlExecutor) => Promise<{id:string}> {
+  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: SqlExecutor, options: Pick<NativeSyncOptions,"binding"|"providerKind">, input: NativeSyncRegistration): Promise<{id:string}> {
+  return nativeSyncRegistration(options,input)(db);
+}
+
+/** No sidecar claim/lease/drainer. Only runCommunicationSyncDispatch executes membership effects. */
+export function createPostgresCommunicationSyncStore(env: PostgresDataGatewayEnv, options: NativeSyncOptions): NativeCommunicationSyncStore {
+  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: string) => { 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 as SqlExecutor));
+    },
+    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:string|null=null;
+        if(purpose!=="tester_program"){
+          const sourceKey=nativeFingerprint(JSON.stringify([fingerprint,purpose,input.state,nativeStamp(row.updated_at)]));
+          workId=(await registerNativeSyncWorkInTransaction(db as SqlExecutor,options,{sourceKey,contactId:fingerprint,normalizedEmail:email,eventType:input.state==="suppressed"?"suppress":"unsubscribe",purpose:purpose as NewsletterMarketingPurpose})).id;
+        }
+        return {updated:true as const,email,purpose:purpose as "tester_program"|NewsletterMarketingPurpose,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 as SqlExecutor).claimBatch({ eventTypes: [eventType], knownEventTypes: [eventType], batchSize: input.batchSize,visibilitySeconds: input.visibilitySeconds,maxAttempts: input.maxAttempts });
+        const events: NewsletterSyncEvent[] = [];
+        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 as NewsletterSyncEventType,
+            purpose: state.purpose as NewsletterMarketingPurpose,payload: payload as Record<string,unknown>, attemptCount: nativeInteger(row.attempts-1,0,19),
+            originProviderKind: state.origin_provider_kind as string | null,originProviderEventId: state.origin_provider_event_id as string | null,remoteProfileId: state.remote_profile_id as string | null,remoteListId: state.remote_list_id as string | null });
+        }
+        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 as SqlExecutor).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 as SqlExecutor).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;
+      });
+    },
+  };
+}