@openlup/platform 0.28.0 → 0.30.0

package/src/marketing/server/postgres/acquisitionCaseRoutines.ts

@@ -0,0 +1,218 @@
+import { Buffer } from "node:buffer";
+import { Pool, type PoolClient } from "pg";
+
+import { ACQUISITION_CASE_CONTRACT_VERSION, acquisitionCaseListResponseSchema, acquisitionCaseProjectionSchema } from "../../acquisitionCaseSchemas.js";
+import type { AcquisitionCaseProjection, AcquisitionCaseFailureKind, AcquisitionCaseListQuery, AcquisitionCaseResult } from "../../contracts/index.js";
+import type {
+  AcquisitionCasePort,
+  AcquisitionCaseSubmitCommand,
+  AcquisitionCaseTransitionCommand,
+} from "../acquisitionCasePorts.js";
+
+const ROLE = "SET LOCAL ROLE platform_acquisition_runtime";
+const SUBMIT = `SELECT public.acquisition_case_submit_v1(
+  $1::text,$2::text,$3::text,$4::text,$5::boolean,$6::text,$7::text,
+  $8::text,$9::text,$10::text,$11::text,$12::text,$13::text,$14::timestamptz
+) AS response`;
+const LIST = "SELECT public.acquisition_case_operator_list_v1($1::uuid,$2::timestamptz,$3::uuid,$4::integer) AS response";
+const GET = "SELECT public.acquisition_case_operator_get_v1($1::uuid,$2::text) AS response";
+const TRANSITION = `SELECT public.acquisition_case_transition_v1(
+  $1::uuid,$2::text,$3::bigint,$4::text,$5::text,$6::text,$7::timestamptz
+) AS response`;
+const ACTIVE_COUNT = "SELECT public.acquisition_case_active_count_v1() AS response";
+
+type Env = { connectionString: string };
+type Options = { poolFactory?: (env: Env) => Pool | Promise<Pool> };
+type Row = Record<string, unknown>;
+
+export function createPostgresAcquisitionCasePort(
+  env: Env,
+  options: Options = {},
+): AcquisitionCasePort {
+  if (!env.connectionString.trim()) throw new Error("acquisition_case_database_url_required");
+  let poolPromise: Promise<Pool> | null = null;
+  const pool = () => poolPromise ??= Promise.resolve(
+    options.poolFactory ? options.poolFactory(env) : new Pool({ connectionString: env.connectionString }),
+  );
+
+  const call = async (sql: string, values: unknown[]): Promise<unknown> =>
+    withRole(await pool(), async (client) => {
+      const result = await client.query(sql, values);
+      return object(result.rows[0])?.response ?? null;
+    });
+
+  return {
+    async submit(command) {
+      if (command.scope !== "public_tester_application" || command.sourceKind !== "tester_application") {
+        return failure("invalid");
+      }
+      try {
+        const request = command.request;
+        const response = object(await call(SUBMIT, [
+          command.idempotencyKey,
+          command.requesterKey,
+          request.contact.email.trim().toLowerCase(),
+          null,
+          request.consent.accepted,
+          request.consent.consentVersion,
+          request.consent.policyVersion,
+          request.consent.locale,
+          command.sourcePath,
+          request.addressReference.source,
+          request.addressReference.reference,
+          request.addressReference.revision,
+          request.addressReference.provenance,
+          command.acceptedAt,
+        ]));
+        return projectionResult(response);
+      } catch (error) {
+        return databaseFailure(error);
+      }
+    },
+
+    async list(query) {
+      if (query.scope !== "public_tester_application") return failure("invalid");
+      const cursor = decodeCursor(query.cursor);
+      if (cursor === undefined) return failure("invalid");
+      try {
+        const response = object(await call(LIST, [
+          query.actorRef,
+          cursor?.createdAt ?? null,
+          cursor?.id ?? null,
+          query.limit,
+        ]));
+        if (!response || !Array.isArray(response.cases)) return failure("unavailable");
+        const parsed = acquisitionCaseListResponseSchema.safeParse({
+          contractVersion: response.contractVersion ?? ACQUISITION_CASE_CONTRACT_VERSION,
+          cases: response.cases,
+          nextCursor: response.nextCursor === null ? null : encodeCursor(response.nextCursor),
+        });
+        return parsed.success ? { ok: true, value: parsed.data } : failure("unavailable");
+      } catch (error) {
+        return databaseFailure(error);
+      }
+    },
+
+    async get(query) {
+      if (query.scope !== "public_tester_application") return failure("invalid");
+      try {
+        const response = object(await call(GET, [query.actorRef, query.caseRef]));
+        if (response?.outcome === "not_found") return failure("not_found");
+        return projectionResult(response);
+      } catch (error) {
+        return databaseFailure(error);
+      }
+    },
+
+    async transition(command) {
+      if (command.scope !== "public_tester_application") return failure("invalid");
+      const target = transitionTarget(command);
+      try {
+        const response = object(await call(TRANSITION, [
+          command.actorRef,
+          command.request.caseRef,
+          command.request.expectedVersion,
+          target,
+          command.request.reason ?? null,
+          command.idempotencyKey,
+          new Date().toISOString(),
+        ]));
+        return projectionResult(response);
+      } catch (error) {
+        return databaseFailure(error);
+      }
+    },
+
+    async activeCount(scope) {
+      if (scope !== "public_tester_application") return failure("invalid");
+      try {
+        const raw = await call(ACTIVE_COUNT, []);
+        const count = typeof raw === "number" ? raw : Number(raw);
+        return Number.isSafeInteger(count) && count >= 0
+          ? { ok: true, value: count }
+          : failure("unavailable");
+      } catch (error) {
+        return databaseFailure(error);
+      }
+    },
+
+    async close() {
+      if (poolPromise) await (await poolPromise).end();
+    },
+  };
+}
+
+async function withRole<T>(pool: Pool, work: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query(ROLE);
+    const value = await work(client);
+    await client.query("COMMIT");
+    return value;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => {});
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+function projectionResult(response: Row | null): AcquisitionCaseResult<AcquisitionCaseProjection> {
+  if (!response) return failure("unavailable");
+  const outcome = response.outcome;
+  if (outcome === "created" || outcome === "replayed" || outcome === "transitioned" || outcome === "found") {
+    const parsed = acquisitionCaseProjectionSchema.safeParse(response.acquisitionCase);
+    return parsed.success
+      ? { ok: true, value: parsed.data, replayed: response.replayed === true }
+      : failure("unavailable");
+  }
+  return failure(outcomeFailure(outcome));
+}
+
+function outcomeFailure(outcome: unknown): AcquisitionCaseFailureKind {
+  if (outcome === "invalid_address") return "invalid";
+  if (outcome === "rate_limited") return "rate_limited";
+  if (outcome === "not_found") return "not_found";
+  if (outcome === "idempotency_conflict" || outcome === "contact_conflict"
+    || outcome === "version_conflict" || outcome === "transition_conflict") return "conflict";
+  return "unavailable";
+}
+
+function databaseFailure(error: unknown): AcquisitionCaseResult<never> {
+  return failure(object(error)?.code === "22023" ? "invalid" : "unavailable");
+}
+
+function failure<T>(kind: AcquisitionCaseFailureKind): AcquisitionCaseResult<T> {
+  return { ok: false, error: { kind } };
+}
+
+function transitionTarget(command: AcquisitionCaseTransitionCommand): string {
+  return ({ approve: "approved", activate: "active", reject: "rejected", withdraw: "withdrawn" } as const)[
+    command.request.transition
+  ];
+}
+
+function encodeCursor(value: unknown): string {
+  const cursor = object(value);
+  if (!cursor || typeof cursor.createdAt !== "string" || typeof cursor.id !== "string") {
+    throw new Error("acquisition_case_cursor_invalid");
+  }
+  return Buffer.from(JSON.stringify({ createdAt: cursor.createdAt, id: cursor.id }), "utf8").toString("base64url");
+}
+
+function decodeCursor(value: AcquisitionCaseListQuery["cursor"]): { createdAt: string; id: string } | null | undefined {
+  if (value === undefined) return null;
+  try {
+    const parsed = object(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+    return parsed && typeof parsed.createdAt === "string" && typeof parsed.id === "string"
+      ? { createdAt: parsed.createdAt, id: parsed.id }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function object(value: unknown): Row | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Row : null;
+}

package/src/marketing/server/postgres/acquisitionEvidenceRoutines.ts

@@ -0,0 +1,103 @@
+import { Pool, type PoolClient } from "pg";
+
+import { ACQUISITION_NEWSLETTER_VERSION, ACQUISITION_SURVEY_VERSION, acquisitionNewsletterConsentResponseSchema, acquisitionSurveyListResponseSchema, acquisitionSurveySubmitResponseSchema } from "../../acquisitionEvidenceSchemas.js";
+import type {
+  AcquisitionEvidenceFailure,
+  AcquisitionEvidencePort,
+  AcquisitionEvidenceResult,
+} from "../../contracts/index.js";
+
+const ROLE = "SET LOCAL ROLE platform_acquisition_runtime";
+const SUBMIT = "SELECT public.acquisition_survey_submit_v1($1::text,$2::text,$3::text,$4::jsonb,$5::timestamptz) AS response";
+const LIST = "SELECT public.acquisition_survey_operator_list_v1($1::uuid,$2::text,$3::integer) AS response";
+const CONSENT = "SELECT public.acquisition_newsletter_consent_v1($1::text,$2::text,$3::text,$4::text,$5::text,$6::boolean,$7::timestamptz,$8::timestamptz) AS response";
+
+type Env = { connectionString: string };
+type Options = { poolFactory?: (env: Env) => Pool | Promise<Pool> };
+type Row = Record<string, unknown>;
+
+export function createPostgresAcquisitionEvidencePort(env: Env, options: Options = {}): AcquisitionEvidencePort {
+  if (!env.connectionString.trim()) throw new Error("acquisition_evidence_database_url_required");
+  let poolPromise: Promise<Pool> | null = null;
+  const pool = () => poolPromise ??= Promise.resolve(
+    options.poolFactory ? options.poolFactory(env) : new Pool({ connectionString: env.connectionString }),
+  );
+  const call = async (sql: string, values: unknown[]): Promise<Row | null> => withRole(
+    await pool(),
+    async (client) => object(object((await client.query(sql, values)).rows[0])?.response),
+  );
+
+  return {
+    async submitSurvey(input) {
+      try {
+        const response = await call(SUBMIT, [input.idempotencyKey, input.caseReference,
+          input.surveyType, JSON.stringify(input.responseData), new Date().toISOString()]);
+        const failure = outcomeFailure(response?.outcome);
+        if (failure) return fail(failure);
+        const parsed = acquisitionSurveySubmitResponseSchema.safeParse({
+          contractVersion: ACQUISITION_SURVEY_VERSION,
+          evidence: response?.evidence,
+          replayed: response?.replayed === true,
+        });
+        return parsed.success ? { ok: true, value: parsed.data } : fail("unavailable");
+      } catch (error) { return databaseFailure(error); }
+    },
+    async listSurveys(input) {
+      try {
+        const response = await call(LIST, [input.actorReference, input.surveyType ?? null, input.limit]);
+        const parsed = acquisitionSurveyListResponseSchema.safeParse({
+          contractVersion: ACQUISITION_SURVEY_VERSION,
+          rows: response?.rows,
+          totalCount: number(response?.totalCount),
+        });
+        return parsed.success ? { ok: true, value: parsed.data } : fail("unavailable");
+      } catch (error) { return databaseFailure(error); }
+    },
+    async applyNewsletterConsent(input) {
+      try {
+        const response = await call(CONSENT, [input.caseReference,input.contactReference,
+          input.eventReference,input.eventType,input.purpose,input.explicitOptInEvidence,
+          input.occurredAt,new Date().toISOString()]);
+        const failure = outcomeFailure(response?.outcome);
+        if (failure) return fail(failure);
+        const parsed = acquisitionNewsletterConsentResponseSchema.safeParse({
+          contractVersion: ACQUISITION_NEWSLETTER_VERSION,
+          eventReference: response?.eventReference,
+          outcome: response?.outcome,
+          consentState: response?.consentState ?? null,
+          auditReference: response?.auditReference,
+          replayed: response?.replayed === true,
+        });
+        return parsed.success ? { ok: true, value: parsed.data } : fail("unavailable");
+      } catch (error) { return databaseFailure(error); }
+    },
+    async close() { if (poolPromise) await (await poolPromise).end(); },
+  };
+}
+
+async function withRole<T>(pool: Pool, work: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN"); await client.query(ROLE);
+    const value = await work(client); await client.query("COMMIT"); return value;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => {}); throw error;
+  } finally { client.release(); }
+}
+
+function outcomeFailure(outcome: unknown): AcquisitionEvidenceFailure | null {
+  if (outcome === "not_found") return "not_found";
+  if (outcome === "idempotency_conflict") return "conflict";
+  if (["recorded","replayed","applied","ignored","stale"].includes(String(outcome))) return null;
+  return "unavailable";
+}
+function databaseFailure<T>(error: unknown): AcquisitionEvidenceResult<T> {
+  return fail(object(error)?.code === "22023" ? "invalid" : "unavailable");
+}
+function fail<T>(kind: AcquisitionEvidenceFailure): AcquisitionEvidenceResult<T> {
+  return { ok: false, error: { kind } };
+}
+function object(value: unknown): Row | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Row : null;
+}
+function number(value: unknown): number { return typeof value === "number" ? value : Number(value); }

package/src/marketing/server/postgres/index.ts

@@ -0,0 +1,3 @@
+/** PostgreSQL acquisition ports; select with the optional pg peer. */
+export { createPostgresAcquisitionCasePort } from "./acquisitionCaseRoutines.js";
+export { createPostgresAcquisitionEvidencePort } from "./acquisitionEvidenceRoutines.js";

package/src/marketing/server/prelaunchAcquisitionDirect.ts

@@ -0,0 +1,121 @@
+import {
+  PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+  prelaunchAcquisitionDetailRequestSchema,
+  prelaunchAcquisitionDetailResponseSchema,
+  prelaunchAcquisitionListRequestSchema,
+  prelaunchAcquisitionListResponseSchema,
+  type PrelaunchAcquisitionLead,
+} from "../prelaunchAcquisitionSchemas.js";
+import type { AcquisitionCaseProjection } from "../contracts/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { AcquisitionCaseFailureKind } from "../contracts/index.js";
+import type { PrelaunchAcquisitionDirectDeps, AcquisitionCaseBindingResolver } from "./directPorts.js";
+
+export function createPrelaunchAcquisitionListHandler(options: PrelaunchAcquisitionDirectDeps) {
+  const { respond, authorize, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorRef = await authorize(req, res);
+    if (!actorRef) return;
+    const request = prelaunchAcquisitionListRequestSchema.safeParse({
+      view: first(req.query.view),
+      cursor: first(req.query.cursor),
+      limit: first(req.query.limit) ?? "25",
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.list(actorRef, {
+      view: "acquisition_case_v1",
+      ...(request.data.cursor ? { cursor: request.data.cursor } : {}),
+      limit: request.data.limit,
+    }));
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = prelaunchAcquisitionListResponseSchema.safeParse({
+      contractVersion: PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+      leads: result.value.cases.map(toLead),
+      nextCursor: result.value.nextCursor,
+    });
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+export function createPrelaunchAcquisitionDetailHandler(options: PrelaunchAcquisitionDirectDeps) {
+  const { respond, authorize, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorRef = await authorize(req, res);
+    if (!actorRef) return;
+    const request = prelaunchAcquisitionDetailRequestSchema.safeParse({
+      sourceRef: first(req.query.sourceRef),
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.get(actorRef, request.data.sourceRef));
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = prelaunchAcquisitionDetailResponseSchema.safeParse({
+      contractVersion: PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+      lead: toLead(result.value),
+    });
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+function toLead(value: AcquisitionCaseProjection): PrelaunchAcquisitionLead {
+  return {
+    sourceRef: value.caseRef,
+    contactRef: value.contactRef,
+    sourceKind: value.sourceKind,
+    consent: value.consent,
+    addressReference: value.addressReference,
+    state: value.state,
+    version: value.version,
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+  };
+}
+
+async function bindingOrError(res: HttpResponse, respond: BffResponder, resolve: AcquisitionCaseBindingResolver) {
+  try {
+    const binding = await resolve();
+    if (binding) return binding;
+  } catch { /* fail closed below */ }
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+  return null;
+}
+
+async function operationOrError<T>(res: HttpResponse, respond: BffResponder, operation: () => Promise<T>): Promise<T | null> {
+  try { return await operation(); }
+  catch {
+    respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+    return null;
+  }
+}
+
+function first(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function badRequest(res: HttpResponse, respond: BffResponder, details?: unknown): void {
+  respond.sendBffError(res, "BAD_REQUEST", "Invalid prelaunch acquisition request", { details });
+}
+
+function invalidResponse(res: HttpResponse, respond: BffResponder): void {
+  respond.sendBffError(res, "INVALID_RESPONSE", "Prelaunch acquisition returned invalid response");
+}
+
+function failure(res: HttpResponse, respond: BffResponder, kind: AcquisitionCaseFailureKind): void {
+  if (kind === "invalid") return badRequest(res, respond);
+  if (kind === "not_found") return respond.sendBffError(res, "NOT_FOUND", "Prelaunch acquisition case not found");
+  if (kind === "conflict") return respond.sendBffError(res, "CONFLICT", "Prelaunch acquisition request conflicts with prior state");
+  if (kind === "rate_limited") return respond.sendBffError(res, "RATE_LIMITED", "Prelaunch acquisition request rate limited");
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+}

package/src/marketing/server/privacyContributor.ts

@@ -0,0 +1,123 @@
+import { personalDataObligationSchema } from "../../identity/contracts/index.js";
+import type { PersonalDataDocument, PersonalDataObligation, PrivacyJson } from "../../identity/contracts/index.js";
+
+interface AuthorizedHumanAdministrator { principalId: string }
+interface ResolvedPrivacySubject {
+  contactId: string | null;
+  principalId: string | null;
+  identity: { [key: string]: PrivacyJson };
+}
+interface ErasureAssessment { obligations: PersonalDataObligation[] }
+/** Structural identity contributor contract without selecting identity's server adapters. */
+export interface MarketingPrivacyContributor<Context> {
+  readonly id: string;
+  readonly version: string;
+  readonly ownedResources: readonly string[];
+  prepareErasure(context: Context): Promise<void>;
+  export(context: Context, subject: ResolvedPrivacySubject): Promise<PersonalDataDocument>;
+  assessErasure(context: Context, subject: ResolvedPrivacySubject): Promise<ErasureAssessment>;
+  eraseOrRetain(context: Context, subject: ResolvedPrivacySubject, assessment: ErasureAssessment, actor: AuthorizedHumanAdministrator): Promise<{
+    contributorId: string; version: string; obligations: PersonalDataObligation[];
+  }>;
+}
+
+export interface MarketingAcquisitionPrivacyPort<Context> {
+  export(context: Context, subject: ResolvedPrivacySubject): Promise<{ records: PrivacyJson; evidence: PrivacyJson; obligations: PersonalDataObligation[] }>;
+  /** Read-only; declare both local resources, including explicit retention policy. */
+  assessErasure(context: Context, subject: ResolvedPrivacySubject): Promise<ErasureAssessment>;
+  eraseOrRetain(context: Context, subject: ResolvedPrivacySubject, assessment: ErasureAssessment, actor: AuthorizedHumanAdministrator): Promise<ErasureAssessment>;
+}
+export interface MarketingRemoteErasureCase {
+  state: "pending" | "requested" | "accepted" | "failed" | "not_bound";
+  fenced: boolean;
+  pendingTargets: number;
+  waitingImports: number;
+}
+export interface MarketingRemoteErasurePort<Context> {
+  /** Read-only subject lookup; return no addresses or provider references. */
+  read(context: Context, subject: ResolvedPrivacySubject): Promise<MarketingRemoteErasureCase | null>;
+  /** Authorized transaction: atomically fence against recreation and record the case, replay-safe per caseId.
+   * In-flight imports and late-import orphan targets remain the case owner's obligations.
+   */
+  openAndFence(context: Context, input: { caseId: string; subject: ResolvedPrivacySubject; actor: AuthorizedHumanAdministrator; openedAt: string }): Promise<MarketingRemoteErasureCase>;
+}
+export interface MarketingPrivacyDependencies<Context> {
+  acquisition: MarketingAcquisitionPrivacyPort<Context> | null;
+  remoteErasure: MarketingRemoteErasurePort<Context> | null;
+  now?: () => Date;
+  randomId(): string;
+}
+const localResources = ["marketing.acquisition-records", "marketing.acquisition-evidence"] as const;
+const remoteResource = "marketing.remote-profile";
+const id = "marketing", version = "marketing.personal-data.v1";
+function obligation(resource: string, disposition: PersonalDataObligation["disposition"], reasonCode: string): PersonalDataObligation {
+  return { owner: id, resource, disposition, reasonCode, remote: resource === remoteResource };
+}
+function unresolved(resource: string): PersonalDataObligation { return obligation(resource, "unresolved", "MARKETING_OWNER_UNAVAILABLE"); }
+function localObligations(value: unknown): PersonalDataObligation[] {
+  const invalid = () => localResources.map(unresolved);
+  if (!Array.isArray(value) || value.length !== localResources.length) return invalid();
+  const parsed = value.map(item => personalDataObligationSchema.safeParse(item));
+  if (parsed.some(item => !item.success)) return invalid();
+  const rows = parsed.map(item => { if (!item.success) throw new Error("marketing_obligation_invalid"); return item.data; });
+  if (rows.some(row => row.owner !== id || row.remote || !localResources.some(resource => resource === row.resource))
+    || localResources.some(resource => rows.filter(row => row.resource === resource).length !== 1)) return invalid();
+  // Owner text is never echoed into receipts; only closed, content-free reasons cross this boundary.
+  return rows.map(row => obligation(row.resource, row.disposition, row.disposition === "erase" ? "LOCAL_OWNER_ERASURE"
+    : row.disposition === "retain" ? "LOCAL_OWNER_RETENTION" : "MARKETING_OWNER_UNAVAILABLE"));
+}
+function validCase(value: MarketingRemoteErasureCase): boolean {
+  return !!value && ["pending", "requested", "accepted", "failed", "not_bound"].includes(value.state)
+    && typeof value.fenced === "boolean" && Number.isSafeInteger(value.pendingTargets) && value.pendingTargets >= 0
+    && Number.isSafeInteger(value.waitingImports) && value.waitingImports >= 0;
+}
+function remoteObligation(value: MarketingRemoteErasureCase | null): PersonalDataObligation {
+  if (value === null) return obligation(remoteResource, "retain", "REMOTE_ERASURE_NOT_REQUESTED");
+  if (!validCase(value)) return unresolved(remoteResource);
+  const reasons = { pending: "REMOTE_ERASURE_PENDING", requested: "REMOTE_ERASURE_REQUESTED", accepted: "REMOTE_ERASURE_ACCEPTED_NOT_OBSERVED",
+    failed: "REMOTE_ERASURE_FAILED", not_bound: value.fenced ? "REMOTE_ERASURE_NOT_BOUND_LOCAL_FENCE_ONLY" : "REMOTE_ERASURE_NOT_BOUND" };
+  return obligation(remoteResource, "retain", `${reasons[value.state]}${value.waitingImports > 0 ? "_WAITING_IMPORTS" : ""}${value.pendingTargets > 0 ? "_PENDING_TARGETS" : ""}`);
+}
+async function ownerCall<T>(run: () => Promise<T>): Promise<T> {
+  try { return await run(); } catch { throw new Error("marketing_privacy_owner_failed"); }
+}
+
+/** Identity orchestrates authorization, assessment, transaction rollback and receipt replay. */
+export function createMarketingPrivacyContributor<Context>(input: MarketingPrivacyDependencies<Context>): MarketingPrivacyContributor<Context> {
+  // Partial ownership cannot establish coverage or permit any erasure effects.
+  const acquisition = input.acquisition && input.remoteErasure ? input.acquisition : null;
+  const remoteErasure = acquisition ? input.remoteErasure : null;
+  const { randomId } = input, now = input.now ?? (() => new Date());
+  return {
+    id, version, ownedResources: [...localResources, remoteResource],
+    async prepareErasure() {},
+    async export(context, subject) {
+      const local = acquisition ? await ownerCall(() => acquisition.export(context, subject)) : null;
+      const remote = remoteErasure ? await ownerCall(() => remoteErasure.read(context, subject)) : null;
+      const validRemote = remote === null || validCase(remote);
+      return { contributorId: id, version, data: { acquisition: local ? { records: local.records, evidence: local.evidence } : null,
+        remoteProfile: { state: validRemote ? remote?.state ?? null : null } },
+      coverage: { complete: false, included: local ? [...localResources] : [], unavailable: [...(local ? [] : localResources), remoteResource] },
+      obligations: [...(local ? localObligations(local.obligations) : localResources.map(unresolved)),
+        remoteErasure ? remoteObligation(remote) : unresolved(remoteResource)] };
+    },
+    async assessErasure(context, subject) {
+      const local = acquisition ? await ownerCall(() => acquisition.assessErasure(context, subject)) : null;
+      const remote = remoteErasure ? await ownerCall(() => remoteErasure.read(context, subject)) : null;
+      return { obligations: [...(local ? localObligations(local.obligations) : localResources.map(unresolved)),
+        remoteErasure ? remoteObligation(remote) : unresolved(remoteResource)] };
+    },
+    async eraseOrRetain(context, subject, assessment, actor) {
+      if (!acquisition || !remoteErasure || assessment.obligations.some(row => row.disposition === "unresolved")) throw new Error("marketing_privacy_unbound");
+      // Identity receipt replay bypasses contributors. Rolled-back attempts may use a fresh ID;
+      // the owner atomically reuses the subject fence and deduplicates each case ID.
+      const remote = await ownerCall(() => remoteErasure.openAndFence(context, { caseId: randomId(), subject, actor, openedAt: now().toISOString() }));
+      if (!validCase(remote) || remote.fenced !== true) throw new Error("marketing_privacy_fence_required");
+      const local = await ownerCall(() => acquisition.eraseOrRetain(context, subject,
+        { obligations: assessment.obligations.filter(row => localResources.some(resource => resource === row.resource)) }, actor));
+      const obligations = localObligations(local.obligations);
+      if (obligations.some(row => row.disposition === "unresolved")) throw new Error("marketing_privacy_disposition_invalid");
+      return { contributorId: id, version, obligations: [...obligations, remoteObligation(remote)] };
+    },
+  };
+}

package/src/marketing/server/research/adminSurveyResponsesHandler.ts

@@ -0,0 +1,78 @@
+import type { HttpRequest, HttpResponse } from "../../../http/index.js";
+import type { BffResponder } from "../../../bff/index.js";
+import {
+  adminSurveyResponsesRequestSchema,
+  adminSurveyResponsesResponseSchema,
+} from "@openlup/core/marketing/research";
+import type { MarketingResearchSurveyResponsesReadPort } from "@openlup/core/marketing/research";
+
+export interface AdminSurveyResponsesHandlerDeps {
+  respond: BffResponder;
+  readPort: MarketingResearchSurveyResponsesReadPort;
+  authorizeAdmin: (req: HttpRequest) => Promise<boolean>;
+}
+
+export function createAdminSurveyResponsesHandler({
+  respond,
+  readPort,
+  authorizeAdmin,
+}: AdminSurveyResponsesHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const authorized = await authorize(req, res, authorizeAdmin, respond);
+    if (!authorized) return;
+
+    const request = adminSurveyResponsesRequestSchema.safeParse({
+      surveyType: firstQueryValue(req.query.surveyType),
+      page: firstQueryValue(req.query.page),
+      pageSize: firstQueryValue(req.query.pageSize),
+      limit: firstQueryValue(req.query.limit),
+    });
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid survey responses request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await readPort.getAdminSurveyResponses(request.data);
+      const response = adminSurveyResponsesResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Survey responses returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Survey responses read failed");
+    }
+  };
+}
+
+async function authorize(
+  req: HttpRequest,
+  res: HttpResponse,
+  authorizeAdmin: (req: HttpRequest) => Promise<boolean>,
+  respond: BffResponder,
+): Promise<boolean> {
+  const { sendBffError } = respond;
+  try {
+    if (await authorizeAdmin(req)) return true;
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return false;
+  }
+
+  sendBffError(res, "UNAUTHORIZED", "Admin session required");
+  return false;
+}
+
+function firstQueryValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}