@openlup/platform 0.28.0 → 0.30.0

package/dist/lifecycle/postgresInstallQualification.d.ts

@@ -0,0 +1,51 @@
+/** 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;
+}
+/**
+ * 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 declare function inspectLegacyPostgresInstallRoles(db: PostgresInstallQuery, request: LegacyPostgresInstallRequest): Promise<LegacyPostgresInstallRoleReport>;

package/dist/lifecycle/postgresInstallQualification.js

@@ -0,0 +1,74 @@
+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) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validRows(value, texts, flags) {
+    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, request) {
+    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;
+    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(row.roles, ["name"], ["login", "superuser", "inherit", "createRole", "createDatabase", "replication", "bypassRls"])
+        || !validRows(row.memberships, ["role", "member", "grantor"], ["admin", "inherit", "set"])) {
+        throw new Error("postgres_install_observation_invalid");
+    }
+    const roles = row.roles;
+    const 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, currentUser: row.currentUser, sessionUser: row.sessionUser,
+        roles, memberships: row.memberships, blockers, rolePrerequisitesMet: blockers.length === 0,
+    };
+}

package/dist/marketing/acquisitionCaseSchemas.d.ts

@@ -0,0 +1,103 @@
+import { z } from "./validation.js";
+export declare const ACQUISITION_CASE_CONTRACT_VERSION: "tester_application_v1";
+export declare const ACQUISITION_CASE_VIEW: "acquisition_case_v1";
+export declare const ACQUISITION_CASE_SOURCE: "tester_application";
+export declare const acquisitionOpaqueReferenceSchema: z.ZodString;
+export declare const acquisitionAddressReferenceSchema: z.ZodObject<{
+    source: z.ZodString;
+    reference: z.ZodString;
+    revision: z.ZodString;
+    provenance: z.ZodString;
+}, z.core.$strict>;
+export declare const acquisitionCaseStateSchema: z.ZodEnum<{
+    rejected: "rejected";
+    active: "active";
+    submitted: "submitted";
+    withdrawn: "withdrawn";
+    approved: "approved";
+}>;
+export declare const acquisitionCaseProjectionSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"tester_application_v1">;
+    caseRef: z.ZodString;
+    contactRef: z.ZodString;
+    sourceKind: z.ZodLiteral<"tester_application">;
+    consent: z.ZodObject<{
+        consentVersion: z.ZodString;
+        policyVersion: z.ZodString;
+        recordedAt: z.ZodString;
+        locale: z.ZodEnum<{
+            en: "en";
+            pl: "pl";
+        }>;
+        sourcePath: z.ZodLiteral<"/tester-application">;
+    }, z.core.$strict>;
+    addressReference: z.ZodNullable<z.ZodObject<{
+        source: z.ZodString;
+        reference: z.ZodString;
+        revision: z.ZodString;
+        provenance: z.ZodString;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        rejected: "rejected";
+        active: "active";
+        submitted: "submitted";
+        withdrawn: "withdrawn";
+        approved: "approved";
+    }>;
+    version: z.ZodNumber;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const acquisitionCaseListRequestSchema: z.ZodObject<{
+    view: z.ZodLiteral<"acquisition_case_v1">;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const acquisitionCaseListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"tester_application_v1">;
+    cases: z.ZodArray<z.ZodObject<{
+        contractVersion: z.ZodLiteral<"tester_application_v1">;
+        caseRef: z.ZodString;
+        contactRef: z.ZodString;
+        sourceKind: z.ZodLiteral<"tester_application">;
+        consent: z.ZodObject<{
+            consentVersion: z.ZodString;
+            policyVersion: z.ZodString;
+            recordedAt: z.ZodString;
+            locale: z.ZodEnum<{
+                en: "en";
+                pl: "pl";
+            }>;
+            sourcePath: z.ZodLiteral<"/tester-application">;
+        }, z.core.$strict>;
+        addressReference: z.ZodNullable<z.ZodObject<{
+            source: z.ZodString;
+            reference: z.ZodString;
+            revision: z.ZodString;
+            provenance: z.ZodString;
+        }, z.core.$strict>>;
+        state: z.ZodEnum<{
+            rejected: "rejected";
+            active: "active";
+            submitted: "submitted";
+            withdrawn: "withdrawn";
+            approved: "approved";
+        }>;
+        version: z.ZodNumber;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const acquisitionCaseActiveCountResponseSchema: z.ZodObject<{
+    activeTesterCount: z.ZodNumber;
+}, z.core.$strict>;
+export declare const acquisitionIdempotencyKeySchema: z.ZodString;
+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/dist/marketing/acquisitionCaseSchemas.js

@@ -0,0 +1,53 @@
+import { z } from "./validation.js";
+export const ACQUISITION_CASE_CONTRACT_VERSION = "tester_application_v1";
+export const ACQUISITION_CASE_VIEW = "acquisition_case_v1";
+export const ACQUISITION_CASE_SOURCE = "tester_application";
+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._:-]*$/);

package/dist/marketing/acquisitionEvidenceSchemas.d.ts

@@ -0,0 +1,105 @@
+import { z } from "./validation.js";
+export declare const ACQUISITION_SURVEY_VERSION: "acquisition_survey_v1";
+export declare const ACQUISITION_NEWSLETTER_VERSION: "acquisition_newsletter_consent_v1";
+export declare const acquisitionSurveySubmitSchema: z.ZodObject<{
+    view: z.ZodLiteral<"acquisition_survey_v1">;
+    caseReference: z.ZodString;
+    surveyType: z.ZodEnum<{
+        producer: "producer";
+        consumer: "consumer";
+    }>;
+    responseData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const acquisitionSurveyEvidenceSchema: z.ZodObject<{
+    evidenceReference: z.ZodString;
+    caseReference: z.ZodString;
+    contactReference: z.ZodString;
+    surveyType: z.ZodEnum<{
+        producer: "producer";
+        consumer: "consumer";
+    }>;
+    responseDigest: z.ZodString;
+    answerCount: z.ZodNumber;
+    recordedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const acquisitionSurveySubmitResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"acquisition_survey_v1">;
+    evidence: z.ZodObject<{
+        evidenceReference: z.ZodString;
+        caseReference: z.ZodString;
+        contactReference: z.ZodString;
+        surveyType: z.ZodEnum<{
+            producer: "producer";
+            consumer: "consumer";
+        }>;
+        responseDigest: z.ZodString;
+        answerCount: z.ZodNumber;
+        recordedAt: z.ZodString;
+    }, z.core.$strip>;
+    replayed: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const acquisitionSurveyListQuerySchema: z.ZodObject<{
+    view: z.ZodLiteral<"acquisition_survey_v1">;
+    surveyType: z.ZodOptional<z.ZodEnum<{
+        producer: "producer";
+        consumer: "consumer";
+    }>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const acquisitionSurveyListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"acquisition_survey_v1">;
+    rows: z.ZodArray<z.ZodObject<{
+        evidenceReference: z.ZodString;
+        caseReference: z.ZodString;
+        contactReference: z.ZodString;
+        surveyType: z.ZodEnum<{
+            producer: "producer";
+            consumer: "consumer";
+        }>;
+        responseDigest: z.ZodString;
+        answerCount: z.ZodNumber;
+        recordedAt: z.ZodString;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+}, z.core.$strip>;
+export declare const acquisitionNewsletterConsentEventSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"acquisition_newsletter_consent_v1">;
+    caseReference: z.ZodString;
+    contactReference: z.ZodString;
+    eventReference: z.ZodString;
+    eventType: z.ZodEnum<{
+        suppress: "suppress";
+        update: "update";
+        subscribe: "subscribe";
+        unsubscribe: "unsubscribe";
+        complaint: "complaint";
+    }>;
+    purpose: z.ZodEnum<{
+        marketing_launch_offer: "marketing_launch_offer";
+        marketing_newsletter: "marketing_newsletter";
+    }>;
+    explicitOptInEvidence: z.ZodDefault<z.ZodBoolean>;
+    occurredAt: z.ZodString;
+}, z.core.$strict>;
+export declare const acquisitionNewsletterConsentResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"acquisition_newsletter_consent_v1">;
+    eventReference: z.ZodString;
+    outcome: z.ZodEnum<{
+        applied: "applied";
+        ignored: "ignored";
+        stale: "stale";
+    }>;
+    consentState: z.ZodNullable<z.ZodEnum<{
+        suppressed: "suppressed";
+        granted: "granted";
+    }>>;
+    auditReference: z.ZodString;
+    replayed: z.ZodBoolean;
+}, z.core.$strip>;
+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/dist/marketing/acquisitionEvidenceSchemas.js

@@ -0,0 +1,55 @@
+import { z } from "./validation.js";
+export const ACQUISITION_SURVEY_VERSION = "acquisition_survey_v1";
+export const ACQUISITION_NEWSLETTER_VERSION = "acquisition_newsletter_consent_v1";
+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(),
+});

package/dist/marketing/analytics/dataLayer.d.ts

@@ -0,0 +1,18 @@
+import type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+export type { AnalyticsSinkAttemptMask, AnalyticsSinkAdmission, AnalyticsCookieConsent, AnalyticsBrowserWindow, AnalyticsDataLayerOptions } from "../contracts/analytics.js";
+import type { AnalyticsEventMap, AnalyticsEventName } from "./noop.js";
+/** Each instance owns loader state; the host supplies browser and deployment policy. */
+export declare function createAnalyticsDataLayer<StepName extends string = string>(options?: AnalyticsDataLayerOptions<StepName>): {
+    readCookieConsent: () => AnalyticsCookieConsent | null;
+    hasAnalyticsConsent: (consent?: AnalyticsCookieConsent | null) => boolean;
+    configuredContainerId: () => string | null;
+    subscribeToAnalyticsConsent: (listener: () => void) => () => void;
+    isAnalyticsLoaderReady: () => boolean;
+    subscribeToAnalyticsLoaderReadiness: (listener: () => void) => () => void;
+    markAnalyticsLoaderReady: () => void;
+    resetAnalyticsLoaderReadiness: () => void;
+    pushAnalyticsConsentDefault: () => void;
+    pushAnalyticsConsentUpdate: (granted: boolean) => void;
+    pushAnalyticsEvent: <K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K]) => boolean;
+    emitAnalyticsEvent: <K extends AnalyticsEventName>(event: K, properties: AnalyticsEventMap<StepName>[K], attempts?: AnalyticsSinkAttemptMask) => AnalyticsSinkAdmission;
+};

package/dist/marketing/analytics/dataLayer.js

@@ -0,0 +1,111 @@
+import { trackDeploymentEvent } from "./noop.js";
+/** Each instance owns loader state; the host supplies browser and deployment policy. */
+export function createAnalyticsDataLayer(options = {}) {
+    const { consentStorageKey = "", consentChangeEvent = "", consentSignalNames, eventPrefix = "", readContainerId = () => null, getWindow = () => undefined } = options;
+    const deploymentSink = options.trackDeploymentEvent ?? trackDeploymentEvent;
+    let analyticsLoaderReady = false;
+    const readinessListeners = new Set();
+    function readCookieConsent() {
+        const browser = getWindow();
+        if (!browser)
+            return null;
+        try {
+            const parsed = JSON.parse(browser.localStorage.getItem(consentStorageKey) ?? "");
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return null;
+            const value = parsed;
+            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()) { return consent?.analytics === true; }
+    function configuredContainerId() { return readContainerId(); }
+    function subscribeToAnalyticsConsent(listener) {
+        const browser = getWindow();
+        if (!browser)
+            return () => undefined;
+        const onStorage = (event) => { if (event.key === consentStorageKey)
+            listener(); };
+        browser.addEventListener("storage", onStorage);
+        browser.addEventListener(consentChangeEvent, listener);
+        return () => {
+            browser.removeEventListener("storage", onStorage);
+            browser.removeEventListener(consentChangeEvent, listener);
+        };
+    }
+    function isAnalyticsLoaderReady() { return analyticsLoaderReady; }
+    function subscribeToAnalyticsLoaderReadiness(listener) {
+        readinessListeners.add(listener);
+        return () => readinessListeners.delete(listener);
+    }
+    function markAnalyticsLoaderReady() {
+        if (analyticsLoaderReady)
+            return;
+        analyticsLoaderReady = true;
+        for (const listener of readinessListeners)
+            listener();
+    }
+    function resetAnalyticsLoaderReadiness() { analyticsLoaderReady = false; }
+    function pushAnalyticsConsentDefault() {
+        pushConsentCommand("default", "denied", "denied");
+    }
+    function pushAnalyticsConsentUpdate(granted) {
+        const analyticsState = granted ? "granted" : "denied";
+        // Read the separate advertising grant at push time; revocation denies all signals.
+        const adState = granted && readCookieConsent()?.marketing === true ? "granted" : "denied";
+        pushConsentCommand("update", analyticsState, adState);
+    }
+    function pushAnalyticsEvent(event, properties) {
+        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(event, properties, attempts = { deployment: true, optional: true }) {
+        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, analyticsState, adState) {
+        const browser = getWindow();
+        if (!consentSignalNames || !browser?.dataLayer)
+            return;
+        const settings = { [consentSignalNames.analytics]: analyticsState };
+        for (const name of consentSignalNames.advertising)
+            settings[name] = adState;
+        function consentCommand(..._args) {
+            // 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/dist/marketing/analytics/noop.d.ts

@@ -0,0 +1,9 @@
+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 declare function initializeDeploymentAnalytics(): void;
+export declare function trackDeploymentEvent<K extends AnalyticsEventName>(_event: K, _properties: AnalyticsEventMap[K]): boolean;
+export declare function syncAdvertisingConsent(): void;
+export declare function trackAdvertisingPurchase(_payload: AnalyticsEventMap["purchase"]): boolean;
+/** Inert composition satisfies the existing platform runtime port. */
+export declare function createNoopAnalytics(): AnalyticsPort;

package/dist/marketing/analytics/noop.js

@@ -0,0 +1,8 @@
+export function initializeDeploymentAnalytics() { }
+export function trackDeploymentEvent(_event, _properties) { return false; }
+export function syncAdvertisingConsent() { }
+export function trackAdvertisingPurchase(_payload) { return false; }
+/** Inert composition satisfies the existing platform runtime port. */
+export function createNoopAnalytics() {
+    return { trackPageView() { }, trackEvent() { } };
+}

package/dist/marketing/analytics/purchaseFacts.d.ts

@@ -0,0 +1,4 @@
+import type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+export type { PurchaseOrder, PurchaseSuppressionReason } from "../contracts/analytics.js";
+import type { AnalyticsEventMap } from "./noop.js";
+export declare function projectPaidPurchase(recap: PurchaseOrder, suppressPurchase?: (reason: PurchaseSuppressionReason) => null): AnalyticsEventMap["purchase"] | null;