@openlup/platform 0.28.0 → 0.30.0

package/src/lifecycle/appUpgrade.ts

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Exact UTF-8 scaffold files; every unlisted path remains application-owned. */
+export interface AppVersionSnapshot {
+  version: string;
+  schema: { min: number; max: number };
+  files: Readonly<Record<string, string>>;
+}
+
+export interface AppUpgradeInput {
+  /** Absolute canonical path (as returned by realpath) of an existing app directory. */
+  root: string;
+  from: AppVersionSnapshot;
+  to: AppVersionSnapshot;
+  /** Observed by the caller; planning and applying execute no database work. */
+  schemaVersion: number;
+}
+
+export type AppUpgradeAction = "create" | "replace" | "remove" | "unchanged" | "preserved" | "already-applied";
+export interface AppUpgradeConflict { path: string; reason: string }
+export interface AppUpgradePlan {
+  fromVersion: string;
+  toVersion: string;
+  schemaVersion: number;
+  files: { path: string; action: AppUpgradeAction }[];
+  conflicts: AppUpgradeConflict[];
+}
+
+export class AppUpgradeConflictError extends Error {
+  constructor(public readonly conflicts: readonly AppUpgradeConflict[]) {
+    super(`Application upgrade refused: ${conflicts.map(({ path, reason }) => `${path || "schema"}: ${reason}`).join("; ")}`);
+    this.name = "AppUpgradeConflictError";
+  }
+}
+
+/** Read-only comparison of explicit predecessor and candidate snapshots. */
+export async function planAppUpgrade(input: AppUpgradeInput): Promise<AppUpgradePlan> {
+  return (await inspectUpgrade(input)).plan;
+}
+
+/**
+ * The caller must hold an exclusive maintenance window over the application tree.
+ * This is not a lock against concurrent editors or hostile filesystem mutation.
+ * All conflicts are checked before any writes. A later I/O failure can leave a
+ * partial upgrade: rerun the same snapshots to recognize exact completed bytes.
+ * Each replacement is atomic on a local filesystem; the complete upgrade is not.
+ * An abrupt process termination can leave a uniquely named temporary file; it is
+ * never treated as a managed app file or resumed operation.
+ * No SQL, dependency install, version marker, deployment or user hook is executed.
+ */
+export async function applyAppUpgrade(input: AppUpgradeInput): Promise<{ plan: AppUpgradePlan; applied: string[] }> {
+  const { root, plan, target } = await inspectUpgrade(input);
+  if (plan.conflicts.length) throw new AppUpgradeConflictError(plan.conflicts);
+  const applied: string[] = [];
+  for (const file of plan.files) {
+    const destination = join(root, file.path);
+    if (file.action === "remove") {
+      await fs.unlink(destination);
+    } else if (file.action === "create" || file.action === "replace") {
+      await fs.mkdir(dirname(destination), { recursive: true });
+      const temporary = join(dirname(destination), `.openlup-${randomUUID()}.tmp`);
+      // Rename replaces this directory entry rather than modifying a possible hardlink.
+      const mode = file.action === "replace" ? (await fs.stat(destination)).mode & 0o777 : 0o600;
+      let handle;
+      try {
+        handle = await fs.open(temporary, "wx", mode);
+        if (file.action === "replace") await handle.chmod(mode);
+        await handle.writeFile(target.get(file.path)!, "utf8");
+        await handle.close();
+        await fs.rename(temporary, destination);
+      } finally {
+        if (handle) {
+          await handle.close();
+          await fs.rm(temporary, { force: true });
+        }
+      }
+    } else continue;
+    applied.push(file.path);
+  }
+  return { plan, applied };
+}
+
+async function inspectUpgrade(input: AppUpgradeInput): Promise<{
+  root: string; plan: AppUpgradePlan; target: Map<string, string>;
+}> {
+  const before = snapshotFiles(input.from), target = snapshotFiles(input.to);
+  const paths = [...new Set([...before.keys(), ...target.keys()])].sort();
+  const aliases = new Set<string>();
+  for (const path of paths) {
+    const alias = path.normalize("NFC").toLowerCase().toUpperCase();
+    if (aliases.has(alias)) throw new Error(`Application upgrade path alias: ${path}`);
+    aliases.add(alias);
+  }
+  const directorySpellings = new Map<string, string>();
+  for (const path of paths) {
+    const components = path.split("/");
+    while (components.length > 1) {
+      components.pop();
+      const directory = components.join("/"), alias = directory.normalize("NFC").toLowerCase().toUpperCase();
+      if (aliases.has(alias)) throw new Error(`Application upgrade file-parent collision: ${path}`);
+      // Parents may not exist yet; both snapshots must still agree on their spelling.
+      const spelling = directorySpellings.get(alias);
+      if (spelling !== undefined && spelling !== directory) throw new Error(`Application upgrade path alias: ${path}`);
+      directorySpellings.set(alias, directory);
+    }
+  }
+  if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 0) throw new Error("Application schema version must be a nonnegative safe integer");
+  const plan: AppUpgradePlan = {
+    fromVersion: input.from.version, toVersion: input.to.version,
+    schemaVersion: input.schemaVersion, files: [], conflicts: [],
+  };
+  for (const snapshot of [input.from, input.to]) {
+    if (input.schemaVersion < snapshot.schema.min || input.schemaVersion > snapshot.schema.max) {
+      plan.conflicts.push({ path: "", reason: `schema ${input.schemaVersion} is outside ${snapshot.version} range ${snapshot.schema.min}..${snapshot.schema.max}` });
+    }
+  }
+  const requestedRoot = resolve(input.root), rootStat = await fs.lstat(requestedRoot);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error("Application upgrade root must be an ordinary directory");
+  const root = await fs.realpath(requestedRoot);
+  if (input.root !== root) throw new Error("Application upgrade root must be an absolute canonical path");
+  for (const path of paths) {
+    const observed = await readFile(root, path);
+    if (typeof observed === "string") {
+      plan.conflicts.push({ path, reason: observed });
+      continue;
+    }
+    const oldBytes = before.has(path) ? Buffer.from(before.get(path)!, "utf8") : null;
+    const newBytes = target.has(path) ? Buffer.from(target.get(path)!, "utf8") : null;
+    const equal = (bytes: Buffer | null) => observed === null ? bytes === null : bytes !== null && observed.equals(bytes);
+    let action: AppUpgradeAction;
+    if (oldBytes !== null && newBytes !== null && oldBytes.equals(newBytes)) {
+      // An upstream-unchanged file carries no write authority over local customization.
+      action = equal(oldBytes) ? "unchanged" : "preserved";
+    } else if (equal(newBytes)) action = "already-applied";
+    else if (equal(oldBytes)) action = newBytes === null ? "remove" : oldBytes === null ? "create" : "replace";
+    else {
+      plan.conflicts.push({ path, reason: "current bytes match neither predecessor nor candidate" });
+      continue;
+    }
+    plan.files.push({ path, action });
+  }
+  return { root, plan, target };
+}
+
+function snapshotFiles(snapshot: AppVersionSnapshot): Map<string, string> {
+  if (!snapshot || typeof snapshot.version !== "string" || !snapshot.version.trim()) throw new Error("Application snapshot needs an explicit version");
+  const range = snapshot.schema;
+  if (!range || !Number.isSafeInteger(range.min) || !Number.isSafeInteger(range.max) || range.min < 0 || range.max < range.min) throw new Error("Application snapshot needs an ordered nonnegative schema range");
+  if (!snapshot.files || typeof snapshot.files !== "object" || Array.isArray(snapshot.files)) throw new Error("Application snapshot files must be a record");
+  const result = new Map<string, string>();
+  for (const [path, content] of Object.entries(snapshot.files)) {
+    const segments = path.split("/");
+    if (!path || Buffer.from(path, "utf8").toString("utf8") !== path || /[\\:]/u.test(path) || [...path].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) || segments.some(segment => !segment || segment === "." || segment === ".." || /[. ]$/u.test(segment)) || segments.some(segment => [".git", "node_modules"].includes(segment.toLowerCase()))) {
+      throw new Error(`Unsafe application upgrade path: ${path}`);
+    }
+    if (typeof content !== "string" || Buffer.from(content, "utf8").toString("utf8") !== content) throw new Error(`Application upgrade content must be valid UTF-8: ${path}`);
+    result.set(path, content);
+  }
+  return result;
+}
+
+/** A string is a structural refusal; null means an absent path. Never follow links. */
+async function readFile(root: string, path: string): Promise<Buffer | null | string> {
+  const segments = path.split("/");
+  let current = root;
+  for (const [index, segment] of segments.entries()) {
+    const parent = current;
+    current = join(current, segment);
+    let stat;
+    try { stat = await fs.lstat(current); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+    // A filesystem alias is not ownership of the differently spelled entry.
+    // Check only after lstat: ENOENT on a case-sensitive store stays absence.
+    if (!(await fs.readdir(parent)).includes(segment)) return "managed path spelling differs from directory entry";
+    if (stat.isSymbolicLink()) return "symlink in managed path";
+    const last = index === segments.length - 1;
+    if (last) return stat.isFile() ? fs.readFile(current) : "managed path is not a regular file";
+    if (!stat.isDirectory()) return "managed parent is not a directory";
+  }
+  return null;
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,19 @@
+export {
+  planAppUpgrade,
+  applyAppUpgrade,
+  AppUpgradeConflictError,
+  type AppVersionSnapshot,
+  type AppUpgradeInput,
+  type AppUpgradeAction,
+  type AppUpgradeConflict,
+  type AppUpgradePlan,
+} from "./appUpgrade.js";
+export {
+  inspectLegacyPostgresInstallRoles,
+  type PostgresInstallQuery,
+  type LegacyPostgresInstallRequest,
+  type PostgresInstallRoleObservation,
+  type PostgresInstallMembershipObservation,
+  type LegacyPostgresInstallBlocker,
+  type LegacyPostgresInstallRoleReport,
+} from "./postgresInstallQualification.js";

package/src/lifecycle/postgresInstallQualification.ts

@@ -0,0 +1,125 @@
+/** Read-only prerequisites of the immutable legacy fresh-install bootstrap, not install readiness. */
+export interface PostgresInstallQuery {
+  query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export interface LegacyPostgresInstallRequest {
+  /** Expected actual login: both current_user and session_user must match. */
+  migrationLogin: string;
+  /** Legacy bootstrap requires this to be the same login as the migrator. */
+  runtimeLogin: string;
+  roleMode: "installer-managed" | "operator-provisioned";
+}
+
+export interface PostgresInstallRoleObservation {
+  name: string;
+  login: boolean;
+  superuser: boolean;
+  inherit: boolean;
+  createRole: boolean;
+  createDatabase: boolean;
+  replication: boolean;
+  bypassRls: boolean;
+}
+
+export interface PostgresInstallMembershipObservation {
+  role: string;
+  member: string;
+  grantor: string;
+  admin: boolean;
+  inherit: boolean;
+  set: boolean;
+}
+
+export type LegacyPostgresInstallBlocker =
+  | "migration_login_mismatch"
+  | "legacy_bootstrap_requires_superuser"
+  | "legacy_bootstrap_requires_shared_runtime_login"
+  | "runtime_login_missing_or_not_login"
+  | "legacy_bootstrap_requires_installer_managed_roles"
+  | "legacy_bootstrap_role_already_exists";
+
+export interface LegacyPostgresInstallRoleReport {
+  scope: "legacy-fresh-bootstrap-role-prerequisites";
+  database: string;
+  currentUser: string;
+  sessionUser: string;
+  roles: PostgresInstallRoleObservation[];
+  memberships: PostgresInstallMembershipObservation[];
+  blockers: { code: LegacyPostgresInstallBlocker; role?: string }[];
+  rolePrerequisitesMet: boolean;
+}
+
+const BOOTSTRAP_ROLES = ["anon", "authenticated", "platform_acquisition_owner", "platform_acquisition_runtime"];
+// One statement observes identities and the relevant role graph in the same statement snapshot.
+// No SQL, identifiers, credentials or catalog expectations come from the caller.
+// Bind functions, cast types and operators independently of the caller's search_path.
+const OBSERVE = `SELECT pg_catalog.current_database() AS database, current_user::pg_catalog.text AS "currentUser",
+  session_user::pg_catalog.text AS "sessionUser",
+  (SELECT COALESCE(pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object('name', rolname, 'login', rolcanlogin,
+    'superuser', rolsuper, 'inherit', rolinherit, 'createRole', rolcreaterole,
+    'createDatabase', rolcreatedb, 'replication', rolreplication, 'bypassRls', rolbypassrls)
+    ORDER BY rolname), '[]'::pg_catalog.jsonb) FROM pg_catalog.pg_roles
+    WHERE rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[]) OR rolname OPERATOR(pg_catalog.=) current_user) AS roles,
+  (SELECT COALESCE(pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object('role', granted.rolname, 'member', member.rolname,
+    'grantor', grantor.rolname, 'admin', m.admin_option, 'inherit', m.inherit_option, 'set', m.set_option)
+    ORDER BY granted.rolname, member.rolname, grantor.rolname), '[]'::pg_catalog.jsonb)
+    FROM pg_catalog.pg_auth_members m
+    JOIN pg_catalog.pg_roles granted ON granted.oid OPERATOR(pg_catalog.=) m.roleid
+    JOIN pg_catalog.pg_roles member ON member.oid OPERATOR(pg_catalog.=) m.member
+    JOIN pg_catalog.pg_roles grantor ON grantor.oid OPERATOR(pg_catalog.=) m.grantor
+    WHERE granted.rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[])
+      OR member.rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[])) AS memberships`;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validRows<T>(value: unknown, texts: string[], flags: string[]): value is T[] {
+  return Array.isArray(value) && value.every(row => isRecord(row)
+    && texts.every(key => typeof row[key] === "string" && row[key].length > 0)
+    && flags.every(key => typeof row[key] === "boolean"));
+}
+
+/**
+ * Observes PostgreSQL 16+ legacy role prerequisites without changing the database.
+ * A true result says nothing about schema inventory, object ACLs, pooling, import safety or hosting.
+ * Query/driver errors are redacted because they can contain connection credentials.
+ */
+export async function inspectLegacyPostgresInstallRoles(
+  db: PostgresInstallQuery,
+  request: LegacyPostgresInstallRequest,
+): Promise<LegacyPostgresInstallRoleReport> {
+  if (![request.migrationLogin, request.runtimeLogin].every(name => typeof name === "string" && name.trim().length > 0)
+    || !["installer-managed", "operator-provisioned"].includes(request.roleMode)) {
+    throw new Error("postgres_install_request_invalid");
+  }
+  let rows: Record<string, unknown>[];
+  try {
+    ({ rows } = await db.query(OBSERVE, [[...new Set([...BOOTSTRAP_ROLES, request.migrationLogin, request.runtimeLogin])]]));
+  } catch {
+    throw new Error("postgres_install_observation_failed");
+  }
+  const row = rows[0];
+  if (rows.length !== 1 || !row
+    || ![row.database, row.currentUser, row.sessionUser].every(value => typeof value === "string" && value.length > 0)
+    || !validRows<PostgresInstallRoleObservation>(row.roles, ["name"], ["login", "superuser", "inherit", "createRole", "createDatabase", "replication", "bypassRls"])
+    || !validRows<PostgresInstallMembershipObservation>(row.memberships, ["role", "member", "grantor"], ["admin", "inherit", "set"])) {
+    throw new Error("postgres_install_observation_invalid");
+  }
+  const roles = row.roles;
+  const blockers: LegacyPostgresInstallRoleReport["blockers"] = [];
+  if (row.currentUser !== request.migrationLogin || row.sessionUser !== request.migrationLogin) blockers.push({ code: "migration_login_mismatch" });
+  if (!roles.some(role => role.name === row.currentUser && role.superuser)) blockers.push({ code: "legacy_bootstrap_requires_superuser" });
+  if (row.currentUser !== request.runtimeLogin) blockers.push({ code: "legacy_bootstrap_requires_shared_runtime_login" });
+  if (!roles.some(role => role.name === request.runtimeLogin && role.login)) blockers.push({ code: "runtime_login_missing_or_not_login" });
+  if (request.roleMode !== "installer-managed") blockers.push({ code: "legacy_bootstrap_requires_installer_managed_roles" });
+  for (const name of BOOTSTRAP_ROLES) {
+    if (roles.some(role => role.name === name)) blockers.push({ code: "legacy_bootstrap_role_already_exists", role: name });
+  }
+  return {
+    scope: "legacy-fresh-bootstrap-role-prerequisites",
+    database: row.database as string, currentUser: row.currentUser as string, sessionUser: row.sessionUser as string,
+    roles, memberships: row.memberships, blockers, rolePrerequisitesMet: blockers.length === 0,
+  };
+}

package/src/marketing/acquisitionCaseSchemas.ts

@@ -0,0 +1,75 @@
+import { z } from "./validation.js";
+
+export const ACQUISITION_CASE_CONTRACT_VERSION = "tester_application_v1" as const;
+export const ACQUISITION_CASE_VIEW = "acquisition_case_v1" as const;
+export const ACQUISITION_CASE_SOURCE = "tester_application" as const;
+
+export const acquisitionOpaqueReferenceSchema = z.string().trim().min(8).max(160)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const dateTimeSchema = z.string().datetime({ offset: true });
+
+export const acquisitionAddressReferenceSchema = z.object({
+  source: z.string().trim().min(1).max(48).regex(/^[a-z][a-z0-9_-]*$/),
+  reference: acquisitionOpaqueReferenceSchema,
+  revision: z.string().trim().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/),
+  provenance: z.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/),
+}).strict();
+
+
+export const acquisitionCaseStateSchema = z.enum([
+  "submitted", "approved", "active", "rejected", "withdrawn",
+]);
+
+export const acquisitionCaseProjectionSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_CASE_CONTRACT_VERSION),
+  caseRef: acquisitionOpaqueReferenceSchema,
+  contactRef: acquisitionOpaqueReferenceSchema,
+  sourceKind: z.literal(ACQUISITION_CASE_SOURCE),
+  consent: z.object({
+    consentVersion: z.string().min(1).max(64),
+    policyVersion: z.string().min(1).max(64),
+    recordedAt: dateTimeSchema,
+    locale: z.enum(["en", "pl"]),
+    sourcePath: z.literal("/tester-application"),
+  }).strict(),
+  addressReference: acquisitionAddressReferenceSchema.nullable(),
+  state: acquisitionCaseStateSchema,
+  version: z.number().int().positive(),
+  createdAt: dateTimeSchema,
+  updatedAt: dateTimeSchema,
+}).strict().superRefine((value, context) => {
+  if (value.state !== "withdrawn" && value.addressReference === null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["addressReference"], message: "active case requires address reference" });
+  }
+});
+
+export const acquisitionCaseListRequestSchema = z.object({
+  view: z.literal(ACQUISITION_CASE_VIEW),
+  cursor: acquisitionOpaqueReferenceSchema.optional(),
+  limit: z.number().int().min(1).max(100).default(25),
+}).strict();
+
+export const acquisitionCaseListResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_CASE_CONTRACT_VERSION),
+  cases: z.array(acquisitionCaseProjectionSchema).max(100),
+  nextCursor: acquisitionOpaqueReferenceSchema.nullable(),
+}).strict();
+
+
+
+
+export const acquisitionCaseActiveCountResponseSchema = z.object({
+  activeTesterCount: z.number().int().nonnegative(),
+}).strict();
+
+export const acquisitionIdempotencyKeySchema = z.string().trim().min(8).max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+
+export type AcquisitionOpaqueReference = z.infer<typeof acquisitionOpaqueReferenceSchema>;
+export type AcquisitionAddressReference = z.infer<typeof acquisitionAddressReferenceSchema>;
+export type AcquisitionCaseState = z.infer<typeof acquisitionCaseStateSchema>;
+export type AcquisitionCaseProjection = z.infer<typeof acquisitionCaseProjectionSchema>;
+export type AcquisitionCaseListRequest = z.infer<typeof acquisitionCaseListRequestSchema>;
+export type AcquisitionCaseListResponse = z.infer<typeof acquisitionCaseListResponseSchema>;
+export type AcquisitionCaseActiveCountResponse = z.infer<typeof acquisitionCaseActiveCountResponseSchema>;
+export type AcquisitionIdempotencyKey = z.infer<typeof acquisitionIdempotencyKeySchema>;

package/src/marketing/acquisitionEvidenceSchemas.ts

@@ -0,0 +1,72 @@
+import { z } from "./validation.js";
+
+export const ACQUISITION_SURVEY_VERSION = "acquisition_survey_v1" as const;
+export const ACQUISITION_NEWSLETTER_VERSION = "acquisition_newsletter_consent_v1" as const;
+
+const caseReference = z.string().regex(/^acquisition-case:[0-9a-f-]{36}$/);
+const contactReference = z.string().regex(/^acquisition-contact:[0-9a-f-]{36}$/);
+const commandKey = z.string().min(8).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]+$/);
+const digest = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const acquisitionSurveySubmitSchema = z.object({
+  view: z.literal(ACQUISITION_SURVEY_VERSION),
+  caseReference,
+  surveyType: z.enum(["producer", "consumer"]),
+  responseData: z.record(z.string(), z.unknown()),
+});
+
+export const acquisitionSurveyEvidenceSchema = z.object({
+  evidenceReference: z.string().regex(/^acquisition-survey:[0-9a-f-]{36}$/),
+  caseReference,
+  contactReference,
+  surveyType: z.enum(["producer", "consumer"]),
+  responseDigest: digest,
+  answerCount: z.number().int().min(1).max(100),
+  recordedAt: z.string().datetime({ offset: true }),
+});
+
+export const acquisitionSurveySubmitResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_SURVEY_VERSION),
+  evidence: acquisitionSurveyEvidenceSchema,
+  replayed: z.boolean(),
+});
+
+export const acquisitionSurveyListQuerySchema = z.object({
+  view: z.literal(ACQUISITION_SURVEY_VERSION),
+  surveyType: z.enum(["producer", "consumer"]).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+
+export const acquisitionSurveyListResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_SURVEY_VERSION),
+  rows: z.array(acquisitionSurveyEvidenceSchema),
+  totalCount: z.number().int().min(0),
+});
+
+export const acquisitionNewsletterConsentEventSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_NEWSLETTER_VERSION),
+  caseReference,
+  contactReference,
+  eventReference: commandKey,
+  eventType: z.enum(["subscribe", "unsubscribe", "suppress", "complaint", "update"]),
+  purpose: z.enum(["marketing_launch_offer", "marketing_newsletter"]),
+  explicitOptInEvidence: z.boolean().default(false),
+  occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+
+export const acquisitionNewsletterConsentResponseSchema = z.object({
+  contractVersion: z.literal(ACQUISITION_NEWSLETTER_VERSION),
+  eventReference: commandKey,
+  outcome: z.enum(["applied", "ignored", "stale"]),
+  consentState: z.enum(["granted", "suppressed"]).nullable(),
+  auditReference: z.string().regex(/^acquisition-consent:[0-9a-f-]{36}$/),
+  replayed: z.boolean(),
+});
+
+export type AcquisitionSurveySubmit = z.infer<typeof acquisitionSurveySubmitSchema>;
+export type AcquisitionSurveyEvidence = z.infer<typeof acquisitionSurveyEvidenceSchema>;
+export type AcquisitionSurveySubmitResponse = z.infer<typeof acquisitionSurveySubmitResponseSchema>;
+export type AcquisitionSurveyListQuery = z.infer<typeof acquisitionSurveyListQuerySchema>;
+export type AcquisitionSurveyListResponse = z.infer<typeof acquisitionSurveyListResponseSchema>;
+export type AcquisitionNewsletterConsentEvent = z.infer<typeof acquisitionNewsletterConsentEventSchema>;
+export type AcquisitionNewsletterConsentResponse = z.infer<typeof acquisitionNewsletterConsentResponseSchema>;

package/src/marketing/analytics/dataLayer.ts

@@ -0,0 +1,100 @@
+import type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+export type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsBrowserWindow, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+import { trackDeploymentEvent } from "./noop.js";
+import type { AnalyticsEventMap, AnalyticsEventName } from "./noop.js";
+
+type ConsentState = "granted" | "denied";
+
+/** Each instance owns loader state; the host supplies browser and deployment policy. */
+export function createAnalyticsDataLayer<StepName extends string = string>(options: AnalyticsDataLayerOptions<StepName> = {}) {
+  const { consentStorageKey = "", consentChangeEvent = "", consentSignalNames, eventPrefix = "",
+    readContainerId = () => null, getWindow = () => undefined } = options;
+  const deploymentSink = options.trackDeploymentEvent ?? trackDeploymentEvent;
+  let analyticsLoaderReady = false;
+  const readinessListeners = new Set<() => void>();
+  function readCookieConsent(): AnalyticsCookieConsent | null {
+    const browser = getWindow();
+    if (!browser) return null;
+    try {
+      const parsed: unknown = JSON.parse(browser.localStorage.getItem(consentStorageKey) ?? "");
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+      const value = parsed as Record<string, unknown>;
+      if (typeof value.necessary !== "boolean" || typeof value.functional !== "boolean"
+        || typeof value.analytics !== "boolean" || typeof value.marketing !== "boolean") return null;
+      return { necessary: value.necessary, functional: value.functional,
+        analytics: value.analytics, marketing: value.marketing };
+    } catch { return null; }
+  }
+  function hasAnalyticsConsent(consent = readCookieConsent()): boolean { return consent?.analytics === true; }
+  function configuredContainerId(): string | null { return readContainerId(); }
+  function subscribeToAnalyticsConsent(listener: () => void): () => void {
+    const browser = getWindow();
+    if (!browser) return () => undefined;
+    const onStorage = (event: StorageEvent) => { if (event.key === consentStorageKey) listener(); };
+    browser.addEventListener("storage", onStorage);
+    browser.addEventListener(consentChangeEvent, listener);
+    return () => {
+      browser.removeEventListener("storage", onStorage);
+      browser.removeEventListener(consentChangeEvent, listener);
+    };
+  }
+  function isAnalyticsLoaderReady(): boolean { return analyticsLoaderReady; }
+  function subscribeToAnalyticsLoaderReadiness(listener: () => void): () => void {
+    readinessListeners.add(listener);
+    return () => readinessListeners.delete(listener);
+  }
+  function markAnalyticsLoaderReady(): void {
+    if (analyticsLoaderReady) return;
+    analyticsLoaderReady = true;
+    for (const listener of readinessListeners) listener();
+  }
+  function resetAnalyticsLoaderReadiness(): void { analyticsLoaderReady = false; }
+  function pushAnalyticsConsentDefault(): void {
+    pushConsentCommand("default", "denied", "denied");
+  }
+  function pushAnalyticsConsentUpdate(granted: boolean): void {
+    const analyticsState: ConsentState = granted ? "granted" : "denied";
+    // Read the separate advertising grant at push time; revocation denies all signals.
+    const adState: ConsentState = granted && readCookieConsent()?.marketing === true ? "granted" : "denied";
+    pushConsentCommand("update", analyticsState, adState);
+  }
+  function pushAnalyticsEvent<K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K]): boolean {
+    const browser = getWindow();
+    if (!consentSignalNames || !browser || !configuredContainerId() || !hasAnalyticsConsent()) return false;
+    if (!browser.dataLayer) {
+      browser.dataLayer = [];
+      pushAnalyticsConsentDefault();
+      pushAnalyticsConsentUpdate(true);
+    }
+    browser.dataLayer.push({ event: `${eventPrefix}${event}`, ...properties });
+    return true;
+  }
+  function emitAnalyticsEvent<K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K],
+    attempts: AnalyticsSinkAttemptMask = { deployment: true, optional: true }): AnalyticsSinkAdmission {
+    let deployment = false;
+    let optional = false;
+    if (attempts.deployment) {
+      try { deployment = deploymentSink(event, properties); } catch { /* Sink failure never gates the product. */ }
+    }
+    if (attempts.optional) {
+      try { optional = pushAnalyticsEvent(event, properties); } catch { /* Independent best-effort admission. */ }
+    }
+    return { deployment, optional };
+  }
+  function pushConsentCommand(action: "default" | "update", analyticsState: ConsentState, adState: ConsentState): void {
+    const browser = getWindow();
+    if (!consentSignalNames || !browser?.dataLayer) return;
+    const settings: Record<string, ConsentState> = { [consentSignalNames.analytics]: analyticsState };
+    for (const name of consentSignalNames.advertising) settings[name] = adState;
+    function consentCommand(..._args: unknown[]) {
+      // Consent commands use the array-like arguments object, not an event object.
+      // eslint-disable-next-line prefer-rest-params
+      browser?.dataLayer?.push(arguments);
+    }
+    consentCommand("consent", action, settings);
+  }
+  return { readCookieConsent, hasAnalyticsConsent, configuredContainerId, subscribeToAnalyticsConsent,
+    isAnalyticsLoaderReady, subscribeToAnalyticsLoaderReadiness, markAnalyticsLoaderReady,
+    resetAnalyticsLoaderReadiness, pushAnalyticsConsentDefault, pushAnalyticsConsentUpdate,
+    pushAnalyticsEvent, emitAnalyticsEvent };
+}

package/src/marketing/analytics/noop.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsEventMap, AnalyticsEventName } from "../contracts/analytics.js";
+export type { AnalyticsStepName, AnalyticsCheckoutItem, AnalyticsPurchaseItem, AnalyticsCheckoutMode, AnalyticsPaymentWaitOutcome, AnalyticsEventMap, AnalyticsEventName } from "../contracts/analytics.js";
+import type { AnalyticsPort } from "@openlup/core/platform-runtime";
+
+export function initializeDeploymentAnalytics(): void {}
+export function trackDeploymentEvent<K extends AnalyticsEventName>(
+  _event: K, _properties: AnalyticsEventMap[K],
+): boolean { return false; }
+export function syncAdvertisingConsent(): void {}
+export function trackAdvertisingPurchase(_payload: AnalyticsEventMap["purchase"]): boolean { return false; }
+/** Inert composition satisfies the existing platform runtime port. */
+export function createNoopAnalytics(): AnalyticsPort {
+  return { trackPageView() {}, trackEvent() {} };
+}

package/src/marketing/analytics/purchaseFacts.ts

@@ -0,0 +1,63 @@
+import type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+export type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+import type { AnalyticsEventMap, AnalyticsPurchaseItem } from "./noop.js";
+
+const MAX_ITEMS = 200;
+
+export function projectPaidPurchase(recap: PurchaseOrder,
+  suppressPurchase: (reason: PurchaseSuppressionReason) => null = () => null,
+): AnalyticsEventMap["purchase"] | null {
+  if (recap.status !== "paid") return suppressPurchase("order_not_paid");
+  if (recap.paymentStatus !== "succeeded") return suppressPurchase("payment_not_succeeded");
+  if (recap.checkoutKind !== "one_time" && recap.checkoutKind !== "subscription_initial"
+    && recap.checkoutKind !== "subscription_renewal") return suppressPurchase("checkout_kind_unsupported");
+  if (!recap.moneyReconciled) return suppressPurchase("money_unreconciled");
+  if (recap.items.length === 0) return suppressPurchase("items_empty");
+  let effectiveNet = 0;
+  const items: AnalyticsPurchaseItem[] = [];
+  for (const item of recap.items) {
+    if (!item.sku) return suppressPurchase("sku_missing");
+    if (!Number.isSafeInteger(item.quantity) || item.quantity <= 0) return suppressPurchase("quantity_invalid");
+    if (item.quantity > MAX_ITEMS) return suppressPurchase("item_limit_exceeded");
+    if (!isNonNegativeSafeInteger(item.catalogTotalGross) || !isNonNegativeSafeInteger(item.effectiveNet)
+      || !isNonNegativeSafeInteger(item.vatRateBps) || item.vatRateBps > 10_000) return suppressPurchase("line_money_invalid");
+    const catalogNet = netFromGross(item.catalogTotalGross, item.vatRateBps);
+    const netDiscount = catalogNet - item.effectiveNet;
+    if (netDiscount < 0) return suppressPurchase("net_discount_invalid");
+    const projected = allocateLineItems({ sku: item.sku, variantCode: item.variantCode,
+      quantity: item.quantity, effectiveNet: item.effectiveNet, netDiscount });
+    if (items.length + projected.length > MAX_ITEMS) return suppressPurchase("item_limit_exceeded");
+    items.push(...projected);
+    effectiveNet += item.effectiveNet;
+  }
+  const tax = recap.totals.tax.amountMinor;
+  const total = recap.totals.total.amountMinor;
+  const effectiveShippingNet = total - tax - effectiveNet;
+  if (!isNonNegativeSafeInteger(effectiveShippingNet)) return suppressPurchase("shipping_net_invalid");
+  return { transaction_id: recap.orderId, currency: recap.totals.total.currency, value: effectiveNet / 100,
+    shipping: effectiveShippingNet / 100, tax: tax / 100,
+    checkout_mode: recap.checkoutKind === "one_time" ? "one_time" : "subscription", items };
+}
+function allocateLineItems(input: { sku: string; variantCode: string | null; quantity: number;
+  effectiveNet: number; netDiscount: number }): AnalyticsPurchaseItem[] {
+  const priceBase = Math.floor(input.effectiveNet / input.quantity);
+  const priceRemainder = input.effectiveNet % input.quantity;
+  const discountBase = Math.floor(input.netDiscount / input.quantity);
+  const discountRemainder = input.netDiscount % input.quantity;
+  const grouped = new Map<string, { priceMinor: number; discountMinor: number; quantity: number }>();
+  for (let position = 0; position < input.quantity; position += 1) {
+    const priceMinor = priceBase + (position < priceRemainder ? 1 : 0);
+    const discountMinor = discountBase + (position < discountRemainder ? 1 : 0);
+    const key = `${priceMinor}:${discountMinor}`;
+    const current = grouped.get(key);
+    if (current) current.quantity += 1;
+    else grouped.set(key, { priceMinor, discountMinor, quantity: 1 });
+  }
+  return [...grouped.values()].map(group => ({ item_id: input.sku,
+    ...(input.variantCode ? { item_variant: input.variantCode } : {}), price: group.priceMinor / 100,
+    discount: group.discountMinor / 100, quantity: group.quantity }));
+}
+function netFromGross(grossMinor: number, vatRateBps: number): number {
+  return Math.round(grossMinor * 10_000 / (10_000 + vatRateBps));
+}
+function isNonNegativeSafeInteger(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; }