@openlup/platform 0.16.0 → 0.18.0

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;
+      });
+    },
+  };
+}

package/src/communications/postgresConsentEvaluator.ts

@@ -0,0 +1,49 @@
+import type { PostgresDataGatewayEnv, PostgresDataGatewayOptions } from "../data/index.js";
+import { evaluateCommunicationPolicy } from "./consentPolicy.js";
+import { defaultCommunicationPurposeRegistry } from "./consentPurposeRegistry.js";
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import type { CommunicationPermissionState } from "./contracts/types.js";
+import { NativeConsentEvaluationUnavailableError, type NativeConsentDecision, type NativeConsentInput } from "./nativeOperations.js";
+import { nativeEmail, nativeFingerprint, nativeText, nativeTransactions } from "./postgresNativeOperations.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 function createPostgresConsentEvaluator(env: PostgresDataGatewayEnv, options: NativeConsentOptions = {}): NativeConsentEvaluator {
+  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 as CommunicationPermissionState : null,legacySequencePaused: paused } }, registry);
+          let activeRecipient: boolean | null = 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/src/communications/postgresDeliveryReconciliation.ts

@@ -0,0 +1,101 @@
+import type { PostgresDataGatewayEnv } from "../data/index.js";
+import type { NativeCommunicationsOptions, NativeDeliveryStore, NativeObservationKind } from "./nativeOperations.js";
+import { nativeEmail, nativeFingerprint, nativeInteger, nativeStamp, nativeText, nativeTime, nativeTransactions } from "./postgresNativeOperations.js";
+const kinds: NativeObservationKind[] = ["sent", "delayed", "delivered", "failed", "bounced", "complained"];
+// Terminal/suppression precedence is monotonic; event chronology remains in the fact log.
+const rank = (kind: NativeObservationKind | null) => kind === null ? -1 : kinds.indexOf(kind);
+export function createPostgresDeliveryReconciliationPort(env: PostgresDataGatewayEnv, options: NativeCommunicationsOptions): NativeDeliveryStore {
+  const binding = nativeText(options.binding);
+  const lane = nativeTransactions(env, options, ["public.communication_native_sends", "public.communication_native_observations", "public.communication_recipient_consents"]);
+  const store: NativeDeliveryStore = {
+    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 as NativeObservationKind | null) || (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 as NativeObservationKind, 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 as NativeObservationKind | null, 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 as NativeObservationKind, occurredAt: nativeStamp(fact.occurred_at), source: fact.source as "poll" | "callback" })) };
+      });
+    },
+  };
+  return store;
+}

package/src/communications/postgresNativeOperations.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { createPostgresRoleFreeTransactionLane, type PgQueryExecutor, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+
+export const nativeFingerprint = (value: string): string => createHash("sha256").update(value).digest("hex");
+export function nativeText(value: unknown, max = 256): string {
+  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: unknown): string {
+  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: unknown): string {
+  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: number, min: number, max: number): number {
+  if (!Number.isInteger(value) || value < min || value > max) throw new Error("native_communications_bound_invalid");
+  return value;
+}
+export function nativeJson(value: unknown): string {
+  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: unknown): string => 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: PostgresDataGatewayEnv, options: PostgresDataGatewayOptions, tables: string[]) {
+  if (!env.connectionString.trim()) throw new Error("communications_database_url_required");
+  const lane = createPostgresRoleFreeTransactionLane(env, options);
+  return {
+    close: lane.close,
+    run: <T>(work: (db: PgQueryExecutor) => Promise<T>): Promise<T> => lane.run(async gateway => {
+      const db = gateway as PgQueryExecutor;
+      // 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/src/communications/postgresNotificationRecipients.ts

@@ -0,0 +1,57 @@
+import { CommunicationConflictError } from "./errors.js";
+import type { PgQueryExecutor, PostgresDataGatewayEnv, PostgresDataGatewayOptions } from "../data/index.js";
+import type { NativeNotificationRecipient, NativeNotificationType } from "./nativeOperations.js";
+import { nativeEmail, nativeStamp, nativeText, nativeTransactions } from "./postgresNativeOperations.js";
+const types: NativeNotificationType[] = ["packaging_digest","new_signup","commerce_payment_critical"];
+function notificationType(value: NativeNotificationType): NativeNotificationType {
+  if (!types.includes(value)) throw new Error("native_notification_type_invalid");
+  return value;
+}
+export interface NativeNotificationRecipientsOptions extends PostgresDataGatewayOptions { /** Verified host operator principal, never request body data. */ 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 function createPostgresNotificationRecipientsPort(env: PostgresDataGatewayEnv, options: NativeNotificationRecipientsOptions): NativeNotificationRecipientsPort {
+  const operator = nativeText(options.operatorId);
+  const lane = nativeTransactions(env, options, ["public.notification_recipients","public.platform_communication_operators","public.platform_human_memberships","public.platform_control_operators"]);
+  const run = <T>(work: (db: PgQueryExecutor) => Promise<T>) => lane.run(async db => {
+    // Match the reference communications control-plane admission, retaining row locks through commit.
+    const allowed = (await db.query(`SELECT o.principal_id FROM public.platform_communication_operators o
+      JOIN public.platform_human_memberships m ON m.principal_id=o.principal_id
+      WHERE o.principal_id=$1 AND o.active AND m.membership_state='active' AND m.role IN ('admin','distributor')
+      AND NOT EXISTS (SELECT 1 FROM public.platform_control_operators c WHERE c.principal_id=o.principal_id) FOR SHARE OF o,m`, [operator])).rows;
+    if (allowed.length !== 1) throw new Error("communications_operator_required");
+    return work(db);
+  });
+  return {
+    close: lane.close,
+    listNotificationRecipients(input) {
+      const type = notificationType(input.notification_type);
+      return run(async db => ({ recipients: (await db.query("SELECT id,email,name,active,notification_type,created_at FROM public.notification_recipients WHERE notification_type=$1 ORDER BY created_at,id", [type])).rows.map(row => {
+        if (typeof row.active !== "boolean" || (row.name !== null && typeof row.name !== "string")) throw new Error("native_notification_row_invalid");
+        return { id: nativeText(row.id),email: nativeEmail(row.email),name: row.name as string | null,active: row.active,notification_type: notificationType(row.notification_type as NativeNotificationType),created_at: nativeStamp(row.created_at) };
+      }) }));
+    },
+    async createNotificationRecipient(input) {
+      const email = nativeEmail(input.email), type = notificationType(input.notification_type);
+      if (input.active !== true || (input.name !== null && typeof input.name !== "string")) throw new Error("native_notification_request_invalid");
+      const name = input.name === null ? null : input.name.trim();
+      if (name !== null && name.length > 256) throw new Error("native_notification_request_invalid");
+      try { return await run(async db => {
+        await db.query("INSERT INTO public.notification_recipients (email,name,notification_type,active) VALUES ($1,$2,$3,true)", [email,name,type]);
+        return { created: true as const,email,notification_type: type };
+      }); } catch (error) { if (error && typeof error === "object" && "code" in error && error.code === "23505") throw new CommunicationConflictError("notification_recipient_conflict"); throw error; }
+    },
+    async updateNotificationRecipient(input) {
+      if (typeof input.active !== "boolean" || Object.keys(input).some(key => !["active","recipientId"].includes(key))) throw new Error("native_notification_request_invalid");
+      return run(async db => { await db.query("UPDATE public.notification_recipients SET active=$2,updated_at=clock_timestamp() WHERE id=$1", [input.recipientId,input.active]); return { updated: true as const,recipientId: input.recipientId }; });
+    },
+    deleteNotificationRecipient(input) {
+      return run(async db => { await db.query("DELETE FROM public.notification_recipients WHERE id=$1", [input.recipientId]); return { deleted: true as const,recipientId: input.recipientId }; });
+    },
+  };
+}

package/src/communications/postgresTransactionalDeliveryStore.ts

@@ -0,0 +1,79 @@
+import {
+  createPostgresRoleFreeTransactionLane,
+  type PostgresDataGatewayEnv,
+  type PostgresDataGatewayOptions,
+} from "../data/index.js";
+import type {
+  TransactionalDeliveryReceipt,
+  TransactionalDeliveryReceiptStore,
+} from "./contracts/transactionalDelivery.js";
+
+interface PostgresTransactionalDeliveryStoreClient {
+  rpc(name: string, args: Record<string, unknown>): PromiseLike<{
+    data: unknown;
+    error: { code?: string; message?: string } | null;
+  }>;
+}
+
+export interface PostgresTransactionalDeliveryStore extends TransactionalDeliveryReceiptStore {
+  close(): Promise<void>;
+}
+
+function failure(name: string, error: { code?: string; message?: string }): Error & { code?: string } {
+  const result = new Error(`${name}_failed: ${error.message ?? error.code ?? "unknown"}`) as Error & { code?: string };
+  result.code = error.code;
+  return result;
+}
+
+function receipt(data: unknown): TransactionalDeliveryReceipt {
+  const value = (Array.isArray(data) ? data[0] : data) as Record<string, unknown> | undefined;
+  if (!value || typeof value !== "object") throw new Error("transactional_delivery_receipt_invalid");
+  const common = {
+    idempotencyKey: String(value.idempotency_key ?? ""),
+    commandFingerprint: String(value.command_fingerprint ?? ""),
+    attemptCount: Number(value.attempt_count ?? 0),
+  };
+  if (value.state === "accepted" && typeof value.delivery_reference === "string" && value.error_code == null) {
+    return { ...common, state: "accepted", deliveryReference: value.delivery_reference, errorCode: null };
+  }
+  if (value.state === "failed" && value.delivery_reference == null && typeof value.error_code === "string") {
+    return { ...common, state: "failed", deliveryReference: null, errorCode: value.error_code };
+  }
+  throw new Error("transactional_delivery_receipt_invalid");
+}
+
+/** Direct-Postgres receipt adapter: one role-free transaction for each store operation. */
+export function createPostgresTransactionalDeliveryStore(
+  env: PostgresDataGatewayEnv,
+  options: PostgresDataGatewayOptions = {},
+  createTransactionLane: typeof createPostgresRoleFreeTransactionLane = createPostgresRoleFreeTransactionLane,
+): PostgresTransactionalDeliveryStore {
+  const transactions = createTransactionLane(env, options);
+  const call = <T>(work: (client: PostgresTransactionalDeliveryStoreClient) => Promise<T>): Promise<T> =>
+    transactions.run((client) => work(client as PostgresTransactionalDeliveryStoreClient));
+  const write = (name: string, args: Record<string, unknown>) => call(async (client) => {
+    const { data, error } = await client.rpc(name, args);
+    if (error) throw failure(name, error);
+    return receipt(data);
+  });
+  return {
+    async readReceipt(idempotencyKey) {
+      return call(async (client) => {
+        const { data, error } = await client.rpc("transactional_delivery_read_receipt", { p_idempotency_key: idempotencyKey });
+        if (error) throw failure("transactional_delivery_read_receipt", error);
+        return Array.isArray(data) && data.length === 0 ? null : receipt(data);
+      });
+    },
+    recordAccepted: (input) => write("transactional_delivery_record_accepted", {
+      p_idempotency_key: input.idempotencyKey,
+      p_command_fingerprint: input.commandFingerprint,
+      p_delivery_reference: input.deliveryReference,
+    }),
+    recordFailed: (input) => write("transactional_delivery_record_failed", {
+      p_idempotency_key: input.idempotencyKey,
+      p_command_fingerprint: input.commandFingerprint,
+      p_error_code: input.errorCode,
+    }),
+    close: () => transactions.close(),
+  };
+}

package/src/communications/preferencesToken.ts

@@ -0,0 +1,62 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export type LegacyCommunicationPreferencePurpose = "tester_program" | "marketing_launch_offer" | "marketing_newsletter";
+
+export interface CommunicationPreferenceTokenPayload<Purpose extends string = LegacyCommunicationPreferencePurpose> {
+  email: string;
+  purpose: Purpose;
+  expiresAt: number;
+}
+
+export function verifyCommunicationPreferenceToken(token: string, secret: string, nowMs?: number): CommunicationPreferenceTokenPayload | null;
+export function verifyCommunicationPreferenceToken<Purpose extends string>(token: string, secret: string, nowMs: number | undefined, registry: CommunicationPurposeRegistry<Purpose>): CommunicationPreferenceTokenPayload<Purpose> | null;
+export function verifyCommunicationPreferenceToken(
+  token: string,
+  secret: string,
+  nowMs = Date.now(),
+  registry?: CommunicationPurposeRegistry<string>,
+): CommunicationPreferenceTokenPayload<string> | null {
+  const parts = token.split(".");
+  if (parts.length !== 2 || !secret) return null;
+  const [encoded, signature] = parts;
+  const expected = hmac(encoded, secret);
+  if (!safeEqual(signature, expected)) return null;
+
+  try {
+    const payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as Record<string, unknown>;
+    const email = typeof payload.email === "string" ? payload.email.trim().toLowerCase() : "";
+    const purpose = payload.purpose;
+    const expiresAt = typeof payload.expiresAt === "number" ? payload.expiresAt : 0;
+    if (!email.includes("@") || expiresAt < nowMs) return null;
+    if (
+      typeof purpose !== "string" || (registry ? !registry.has(purpose) :
+      purpose !== "tester_program" &&
+      purpose !== "marketing_launch_offer" &&
+      purpose !== "marketing_newsletter")
+    ) {
+      return null;
+    }
+    return { email, purpose, expiresAt };
+  } catch {
+    return null;
+  }
+}
+
+export function createCommunicationPreferenceToken<Purpose extends string = LegacyCommunicationPreferencePurpose>(
+  payload: CommunicationPreferenceTokenPayload<Purpose>,
+  secret: string,
+): string {
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `${encoded}.${hmac(encoded, secret)}`;
+}
+
+function hmac(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(value).digest("hex");
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/communications/publicPreferenceToken.ts

@@ -0,0 +1,68 @@
+import type { CommunicationPurposeRegistry, CommunicationPurposeDefinition } from "./contracts/consent.js";
+import type { CommunicationPreferenceTokenPayload } from "./preferencesToken.js";
+
+export interface PublicPreferenceTokenSupabaseClient {
+  rpc(fn: string, args: Record<string, unknown>): Promise<{ data: unknown; error?: unknown }>;
+}
+
+export type PublicPreferenceState = "denied" | "suppressed";
+
+export function createSupabasePublicPreferenceTokenPort(
+  client: PublicPreferenceTokenSupabaseClient,
+) {
+  return {
+    async updatePreference(payload: CommunicationPreferenceTokenPayload, state: PublicPreferenceState) {
+      const contact = await client.rpc("communication_touch_contact", {
+        p_email: payload.email,
+        p_first_name: null,
+        p_last_name: null,
+        p_status: "active",
+        p_metadata: { source: "public_communication_preferences" },
+      });
+      if (contact.error || typeof contact.data !== "string") {
+        throw new Error("Communication contact write failed");
+      }
+
+      const event = await client.rpc("communication_record_permission_event", {
+        p_contact_id: contact.data,
+        p_purpose: payload.purpose,
+        p_state: state,
+        p_source: "public_communication_preferences",
+        p_source_ref: { route: "/api/bff/communications/preferences", purpose: payload.purpose },
+        p_reason: "user_preference_update",
+        p_metadata: {
+          actorType: "contact_self_service",
+          captureMethod: "preference_token",
+        },
+        p_captured_at: new Date().toISOString(),
+        p_create_sync_event: payload.purpose !== "tester_program",
+      });
+      if (event.error) throw new Error("Communication preference write failed");
+
+      return {
+        updated: true,
+        email: payload.email,
+        // Keep the legacy adapter declaration expanded when the token default names a type alias.
+        purpose: payload.purpose as "marketing_launch_offer" | "marketing_newsletter" | "tester_program",
+        state,
+      };
+    },
+  };
+}
+
+/** The host owns persistence and any synchronization policy for registered purposes. */
+export function createRegisteredPublicPreferenceTokenPort<Purpose extends string>(input: {
+  registry: CommunicationPurposeRegistry<Purpose>;
+  persist: (payload: CommunicationPreferenceTokenPayload<Purpose>, state: PublicPreferenceState,
+    definition: CommunicationPurposeDefinition<Purpose>) => Promise<unknown>;
+}) {
+  const { registry, persist } = input;
+  return {
+    async updatePreference(payload: CommunicationPreferenceTokenPayload<Purpose>, state: PublicPreferenceState) {
+      if (!registry.has(payload.purpose)) throw new Error("unregistered_communication_purpose");
+      if (state !== "denied" && state !== "suppressed") throw new Error("communication_preference_state_invalid");
+      const definition = registry.purposes.find(item => item.id === payload.purpose)!;
+      return persist(payload, state, definition);
+    },
+  };
+}