@openlup/platform 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -10,6 +10,225 @@ in the source repository.
 
 ## [Unreleased]
 
+## [0.29.0]
+
+- Publishable on the npm `latest` dist-tag as `0.29.0`, from tag
+  `openlup-platform-v0.29.0`.
+
+Adds experimental browser-safe marketing runtime contracts and a type-only
+contracts entry through unchanged schema movement and reference import rebinding.
+Core research remains the compatibility owner. Parsing, defaults, issue details
+and order, and existing inferred input/output types retain their behavior.
+
+Migration: No observable divergence is introduced for existing reference consumers; shims retain their exported names and schema object identities.
+Migration: New public subpath `@openlup/platform/marketing` exposes browser-safe runtime contracts without a server entry.
+Migration: New public subpath `@openlup/platform/marketing/contracts` exposes types only, with no Zod or runtime-module imports.
+Migration: New public export `ACQUISITION_CASE_CONTRACT_VERSION` is available from `@openlup/platform/marketing`.
+Migration: New public export `ACQUISITION_CASE_VIEW` is available from `@openlup/platform/marketing`.
+Migration: New public export `ACQUISITION_CASE_SOURCE` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionOpaqueReferenceSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionAddressReferenceSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionCaseStateSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionCaseProjectionSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionCaseListRequestSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionCaseListResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionCaseActiveCountResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionIdempotencyKeySchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `ACQUISITION_SURVEY_VERSION` is available from `@openlup/platform/marketing`.
+Migration: New public export `ACQUISITION_NEWSLETTER_VERSION` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionSurveySubmitSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionSurveyEvidenceSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionSurveySubmitResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionSurveyListQuerySchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionSurveyListResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionNewsletterConsentEventSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `acquisitionNewsletterConsentResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `marketingResearchJsonSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `researchSurveyTypeSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `adminSurveyResponsesRequestSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `adminSurveyResponseRowSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `adminSurveyResponsesResponseSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `researchSurveySubmitRequestSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public export `researchSurveySubmitResponseSchema` is available from `@openlup/platform/marketing` with its core object identity.
+Migration: New public type `AcquisitionOpaqueReference` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionAddressReference` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseState` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseProjection` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseListRequest` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseListResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseActiveCountResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionIdempotencyKey` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionSurveySubmit` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionSurveyEvidence` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionSurveySubmitResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionSurveyListQuery` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionSurveyListResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionNewsletterConsentEvent` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionNewsletterConsentResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `MarketingResearchJson` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `ResearchSurveyType` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AdminSurveyResponsesRequest` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AdminSurveyResponseRow` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AdminSurveyResponsesResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `ResearchSurveySubmitRequest` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `ResearchSurveySubmitResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `MarketingResearchSurveyResponsesReadPort` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `MarketingResearchSurveyRequestHeaders` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `MarketingResearchSurveySubmitPort` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: `en|pl` locale restriction is known debt tied to the persisted CHECK; locale widening needs a future migration and is outside M13 scope.
+Migration: Retired acquisition case submit/transition request and response contracts and the app-owned client-version binding are intentionally not published.
+Migration: New public export `PRELAUNCH_ACQUISITION_VIEW` is available from `@openlup/platform/marketing`.
+Migration: New public export `PRELAUNCH_ACQUISITION_CONTRACT_VERSION` is available from `@openlup/platform/marketing`.
+Migration: New public export `prelaunchAcquisitionListRequestSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `prelaunchAcquisitionDetailRequestSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `prelaunchAcquisitionLeadSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `prelaunchAcquisitionListResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public export `prelaunchAcquisitionDetailResponseSchema` is available from `@openlup/platform/marketing`.
+Migration: New public type `AcquisitionCaseFailureKind` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseResult` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseListQuery` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCaseGetQuery` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionCasePort` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionEvidenceFailure` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionEvidenceResult` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `AcquisitionEvidencePort` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `PrelaunchAcquisitionListRequest` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `PrelaunchAcquisitionDetailRequest` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `PrelaunchAcquisitionLead` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `PrelaunchAcquisitionListResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: New public type `PrelaunchAcquisitionDetailResponse` is available from `@openlup/platform/marketing` and `@openlup/platform/marketing/contracts`.
+Migration: The rich prelaunch DTO and retired acquisition case submit/transition port methods and commands are intentionally not published.
+Migration: The marketing runtime entry configures the shared Zod instance in jitless mode on load, the same as the pricing, catalog and communications entries; the type-only marketing/contracts entry has no runtime initialization.
+
+Adds experimental Node-only marketing server factories through unchanged
+acquisition, research and PostgreSQL algorithm movement. Host composition retains
+routing, environment, authorization, observed wrappers and notification copy.
+Browser marketing entries retain their isolated schema/type-only boundaries.
+
+Migration: New public subpath `@openlup/platform/marketing/server` contains acquisition case handlers, direct acquisition history and prelaunch reads, survey evidence and consent commands, research handlers and managed survey orchestration.
+Migration: PostgreSQL port factories are published separately under `@openlup/platform/marketing/server/postgres` so the server entry does not load the existing optional `pg` peer. Select `/postgres` with that peer installed. Reference bindings load the adapter lazily after their bundle and connection guards. SQL text, signatures, role selection, pool creation and transaction handling retain their behavior.
+Migration: `createAdminClientsTestersDirectHandler` maps to the neutral package symbol `createAcquisitionCaseListDirectHandler`; `createTesterProgramActiveCountDirectHandler` maps to `createAcquisitionCaseActiveCountDirectHandler`. The reference retains both original factory names and route registrations.
+Migration: `handleAcquisitionSurveySubmit`, `handleAcquisitionSurveyList` and `handleAcquisitionNewsletterConsent` compose `createAcquisitionSurveySubmitDirectHandler`, `createAcquisitionSurveyListDirectHandler` and `createAcquisitionNewsletterConsentDirectHandler`, respectively. Successful evidence values remain forwarded without response-schema validation.
+Migration: Direct factories receive the host BFF responder, authorization callback and binding resolver. Acquisition list/count additionally receive the direct-bundle predicate at its original guard position. Prelaunch/evidence bundle and request-view dispatch remain with host callers; no additional guard is introduced.
+Migration: Research submit/admin handler dependencies receive the BFF responder and use platform HTTP types. Research schemas and ports retain the `@openlup/core/marketing/research` compatibility owner. Delivery types retain their communications/contracts owner.
+Migration: Managed survey submission receives `renderNotificationHtml(type, responseData, id)` and `notificationSubject(type, now)`. HTML renders before the subject clock read, after policy filtering. The host retains subject/HTML copy and escaping; rendered values reach delivery unchanged.
+Migration: Server-only structural submit/transition request and command types retain the historical adapter signatures without adding schemas or changing either browser entry. Retired route factories, terminal refusals, admin auth binding, observed wrappers and raw signed consent ingress remain application-owned.
+Migration: Reference acquisition handler and PostgreSQL adapter paths retain thin package re-exports; runtime bindings retain lazy adapter imports. Reference research handler files bind the responder, and managed submission binds notification copy while retaining live host configuration reads. Prelaunch rich read models and admin leads remain application-owned.
+Migration: Neutral characterization lives under `packages/platform/test/marketing/server/`, including the complete survey/consent direct-handler witness. Six superseded reference test files are removed: acquisition case handlers, both PostgreSQL adapters, prelaunch direct handlers, research submit handler and research admin responses handler. Each asserts only package-owned behavior.
+Migration: Reference direct acquisition tests retain retirement and real admin-auth assertions. Reference prelaunch route tests and evidence direct tests retain host composition coverage. Managed submission retains only reference-side copy/escaping coverage; package tests assert the synthetic renderer seam and ordering.
+Migration: Real PostgreSQL parity lives at `tests/postgres/acquisitionEvidenceParity.test.ts`, imports package factories from `/marketing/server/postgres`, applies the hash-checked manifest prefix and connects all ports using a login granted only runtime-role membership. Missing Docker throws instead of skipping. The fixture owner is used only for setup, state inspection and the donor's append-only trigger proof; separate runtime-role mutation assertions retain privilege-denial coverage in the same case. The witness retains 11 cases. Test rows use deterministic synthetic identifiers and timestamps, and emails use `example.invalid`.
+Migration: The installed consumer exercises a historical count and a conflict refusal with injected bindings without optional peers. The `/postgres` entry receives missing-peer import refusal and selected-peer factory/refusal checks through the existing adapter proof. One package-boundary bundle case prevents the server entry from reaching PostgreSQL adapters or `pg`, bringing the additive seam cases to seven within the eight-case limit. Exact export, API and package-smoke inventories include both server entries; artifact caps, dependencies, migrations and grants are unchanged.
+
+The browser-safe marketing surface provides inert analytics defaults, independently attempted local sinks, injected route policy, paid purchase projection and historical consent-time selection. The reference application binds its existing policy and wire names while preserving its purchase transcript. Local admission booleans establish synchronous acceptance only, never delivery.
+
+Migration: `AnalyticsStepName<StepName = string>` and `AnalyticsEventMap<StepName = string>` accept host step literals instead of a product-specific union. `AnalyticsCheckoutItem`, `AnalyticsPurchaseItem`, `AnalyticsCheckoutMode`, `AnalyticsPaymentWaitOutcome` and `AnalyticsEventName` retain the neutral event vocabulary. Types are also available type-only through `./marketing/contracts`.
+Migration: `createNoopAnalytics` reuses the existing core `AnalyticsPort`. `initializeDeploymentAnalytics`, `trackDeploymentEvent`, `syncAdvertisingConsent` and `trackAdvertisingPurchase` are inert defaults.
+Migration: The donor-only transport ownership field and provider-specific purchase envelope, transport result and transport types are excluded private transport concerns; hosts extend their own event map outside the package.
+Migration: `createAnalyticsDataLayer` replaces module-global mutable state with per-instance state. `AnalyticsDataLayerOptions` injects consent storage/event names, event prefix, container reader, deployment callback and browser access. Defaults are inert. `AnalyticsBrowserWindow`, `AnalyticsCookieConsent`, `AnalyticsSinkAttemptMask` and `AnalyticsSinkAdmission` describe those seams. Host bindings retain historical literals. Consent command arguments, ordering, parse rules, push-time advertising grants and independent synchronous admission are preserved; no pre-consent replay is added.
+Migration: Hosts must supply `AnalyticsDataLayerOptions.consentSignalNames` to enable optional event admission and consent commands: one `analytics` wire name and ordered `advertising` wire names. Omission pushes no consent commands and returns false from `pushAnalyticsEvent`, even with browser access, a container and stored consent; deployment sink attempts are unaffected. Supplied settings retain the analytics key first, then advertising keys in host order, with unchanged consent values.
+Migration: `createAnalyticsRoutePolicy` takes required `AnalyticsRoutePolicyInput` public paths, redirect sources and sensitive sets; there is no ambient route manifest or default sensitive-path policy. `normalizeAnalyticsPathname` preserves normalization. The returned optional-route eligibility method uses a neutral name; hosts alias their historical name.
+Migration: `projectPaidPurchase`, structural `PurchaseOrder` and `PurchaseSuppressionReason` preserve paid allocation, grouping, residual shipping, cap and ordered refusal logic. Currency is a plain string with no ambient currency initialization. The reference guards unsupported kinds before projection through a null input, preserving its renewal refusal and order/payment precedence; the package admits renewal as subscription, matching the donor.
+Migration: `selectMarketingHistoricalConsentTime`, `MarketingHistoricalConsentCommand`, `MarketingHistoricalConsentState` and `MarketingHistoricalConsentResult` expose only chronology facts and the exact compared state literals. Command authorization, persistence and workers stay with the host.
+Migration: `createAnalyticsContextHandler` is exported only by `./marketing/server`, with server-only `AnalyticsContextHandlerDeps`, `AnalyticsContextPersistencePort`, `AnalyticsContextStoreResolver` and `AnalyticsContextCapabilityCrypto`. Platform `HttpRequest`/`HttpResponse` and a required host `BffResponder` replace application HTTP/envelope imports; the host keeps its route path and observability wrapper.
+Migration: The context handler requires an `isEnabled` reader instead of reading an ambient flag. The host retains the flag name and exact enabled-value comparison; the package has no enabling default. Method, flag, origin and strict request-schema refusal order and error codes/messages are preserved. The schema uses the package's jitless validation wrapper.
+Migration: `AnalyticsContextHandlerDeps.clientIdField` is a required host binding for the historical client-id wire field name. Each handler builds its strict schema once with that key, retaining the numeric-dot-numeric pattern, 64-character limit, optional field, `explicitGrant` default false and granted-requires-client-id refusal. Internal and persistence fields remain `clientId`; hosts retain their serving wire names.
+Migration: The host supplies `capabilityCrypto.mintToken` and `hashToken` instead of built-in cryptography, and `cookieName` as the historical compatibility input. Minting must provide opaque 32-byte lowercase hexadecimal tokens and hashing must preserve the host's cryptographic digest. Cookie parsing still selects the first matching name, accepts only 64 lowercase hexadecimal characters and hashes the token; mint timing, cookie attributes and explicit no-store placement are unchanged.
+Migration: `resolveStore` replaces the application gateway lookup; null still refuses with `UPSTREAM_UNAVAILABLE`. `AnalyticsContextPersistencePort.syncContext` receives token hash, granted and client id, and `enrollSubscriptions` receives the verified subject and context hash. These throwing operations replace the application RPC-call wrapper; the host keeps RPC names, argument translation, error-to-throw handling and gateway service authority. Only literal true is active. No default persistence or portable SQL exists, and no reference route is added; a host must supply persistence before mounting the handler.
+Migration: Required `readAccessToken` and `resolveTrustedSubject` bindings replace application authentication imports. The host verifies the bearer under its service authority; invalid bearer grants still refuse before writes, withdrawal needs no identity, and enrollment uses only the verified subject. Explicit regrant replacement, revoked predecessor retention and `{ active }` responses are unchanged. An active result is a local context fact, never delivery; telemetry context failure never gates commerce.
+
+Extend the experimental browser-safe `@openlup/platform/marketing` entry with
+JSON-LD serialization and graphs, route URLs and hreflang, an ordered head
+descriptor and contact/legal plain-data projections. Contact/legal/privacy
+content contracts are type-only exports from `@openlup/platform/marketing/contracts`
+and the runtime entry. Applications supply all identity, origin, locale, image,
+document and processor facts. Responsibility-specific source files re-export
+through the existing marketing barrel without adding a subpath, renderer,
+dependency, network call or application policy. Fresh synthetic conformance and
+browser-bundle tests, API declaration snapshots and the installed consumer
+witness both entries.
+
+Donor divergences: entity facts, lifecycle-selected organization type, contact
+type/languages, image URLs/dimensions, route registry, default locale and social
+metadata become explicit inputs. Product brand prefixing, fixed category,
+audience, fallback weight and image-slug lookup are removed; category, images,
+SKU, GTIN and net content are caller supplied or omitted. The fixed locale union
+becomes strings, and FAQ fields use neutral question/answer names. The private
+image variant helper, language detection and unregistered-route alternate escape
+hatch remain application concerns. The head's canonical input uses the injected
+route contract instead of the donor's loose absolute-URL passthrough.
+The head requires application-supplied image width, image height and Twitter
+handle, and emits `og:image:width`, `og:image:height` and `twitter:site`
+unconditionally in donor order. `og:locale:alternate` remains conditional on
+a supplied alternate locale.
+
+Contact shaping uses supplied support email, shared organization facts, address
+text and ordered registration label/value pairs in place of private identity
+constants and country-specific identifiers. The optional `registrationAuthority`
+line is absent only when its input is undefined; supplied blank company lines
+are retained. Legal shaping takes supplied title, intro and ordered title/body
+sections in place of fixed translation keys and section inventories. The
+last-updated text is optional; supplied blank text is retained. Page markup,
+translations, navigation and other contact copy remain application-owned.
+Privacy processor disclosures are new structural types, with no projection.
+
+The reference `SeoHead` adapter renders the descriptor through the existing
+`react-helmet-async` dependency with `defer={false}`, removes unmanaged shell
+canonical/alternate links after client commit only in the host-supplied `csr`
+render mode (as in the donor), and emits the serialized JSON-LD
+unchanged. These donor host behaviours stay outside the package. The adapter
+has no serving-route mount; mounting is a later integration. Its tests witness
+hidden-document commits, hostile script data and shell canonical replacement.
+
+Migration: none. Both entries are extended additively; no SQL or application route changes.
+
+The experimental `createMarketingContribution` helper in
+`@openlup/platform/composition` describes selected marketing callables as an inert
+`marketing` capability providing `./marketing`, `./marketing/contracts` and
+`./marketing/server`, depending on identity's `./identity/contracts` runtime
+obligation schema.
+Handlers are projected to descriptors without `handle`; ports, routes and
+triggers retain supplied callable identity. Duplicate registration identities
+refuse, and null ports remain required without creating callable bindings.
+
+Divergences from the donor: no donor composition exists; this helper supplies
+descriptors only; no worker, route or schedule is installed.
+
+Migration: Import `createMarketingContribution` from `@openlup/platform/composition` and supply already-bound operations, handler registrations, routes, schedules and host schema requirements explicitly.
+Migration: Bind each required operation under `@openlup/platform/marketing:<name>`; a null operation remains a Core readiness obligation and reports `OPENLUP_E_PORT_MISSING` until bound.
+Migration: The helper invokes no operation during construction. Host admission and installation of workers, routes and schedules remain application-owned.
+
+The existing `./marketing/server` entry additionally exports the marketing privacy
+contributor and default-off binding. Both complete owner ports and explicit
+enablement select one contributor, shared by the callables supplied to composition.
+Unbound or partial ownership reports unavailable coverage and unresolved
+obligations; identity refuses erasure before owner effects. Identity owns the
+subscriptions veto, receipt replay and rollback. The fence runs only during
+`eraseOrRetain`, after all assessments; fence failure throws without owner text.
+Accepted provider requests retain an accepted-not-observed reason and never
+claim deletion or complete remote export coverage.
+
+Donor divergences: worker, operator and store stay app-owned. Only O18 outcomes
+and fence semantics are contributed; provider calls, claims, retries, schedules,
+SQL and late-import orphan handling remain with their owners. The reference
+privacy graph leaves marketing unselected, and marketing privacy coverage there
+remains an open gap. Raw managed questionnaires and other processors are outside
+this contributor's coverage.
+
+Migration: Import `createMarketingPrivacyBindings` and its owner port types from `@openlup/platform/marketing/server`; bind both complete transactional owners and set `enabled: true` explicitly to select a contributor.
+Migration: Register the returned contributor with identity and pass the returned `exportPersonalData`, `assessErasure` and `eraseOrRetain` callables as the marketing record to `createMarketingContribution`; disabled or partial bindings expose null callables.
+Migration: Compose identity's `./identity/contracts` module dependency and preserve its assessment-before-mutation, subscriptions veto, receipt replay and unit-of-work rollback contract.
+Migration: Keep remote profile coverage unavailable; accepted requests and outstanding imports or targets do not establish observed deletion. The reference requires a separately authorized owner binding before marketing privacy coverage can be claimed.
+
+Declaration repair: Privacy owner ports and `MarketingPrivacyContributor` use
+local structural types and identity's `./identity/contracts` types, preserving
+compatibility with identity's contributor without referencing its main entry.
+`./marketing/server` remains free of the optional `pg` peer in strict installed
+declaration compilation; only `./marketing/server/postgres` selects that peer.
+The runtime obligation schema still comes from `./identity/contracts`.
+Identity's public surface, privacy execution and the 16-case K5 budget are unchanged.
+
+- Packed root-documentation budget: the docs-gzip cap in release-gates.json rises from 57,344 B to 73,728 B, approved by the owner on 2026-10-26, because the assembled 0.29.0 notes measured 63,226 B; no other cap changes.
+
 ## [0.28.0]
 
 - Publishable on the npm `latest` dist-tag as `0.28.0`, from tag
@@ -314,21 +533,3 @@ Migration: Subscription finalize validates retained acquisition terms under the
 Migration: The acquisition terms reader refuses absent effective terms; the no-policy finalize compatibility branch remains available.
 Migration: New-purchase stock reads use ATP with renewal exemption fixed false, bounded SKU arrays and conservative stale reporting. The service-only reader uses owner privileges with `SECURITY DEFINER` and `search_path = pg_catalog, pg_temp`.
 Migration: Starter graduation admits 14, 21 or 28 days, while provisional creation uses the retained starter interval and subscription timezone default. Rolling back below the forward with a 21-day marker is unsupported; roll forward.
-
-## [0.26.0]
-
-- Publishable on the npm `latest` dist-tag as `0.26.0`, from tag
-  `openlup-platform-v0.26.0`.
-
-Managed dunning attempt replay.
-
-Carry the exact applied failure attempt through renewal propagation. Managed
-same/stale observations replay the canonical result; newer attributed failures
-advance and revoke prior recovery authority, including used tokens.
-
-Migration: `CycleChargeFailurePropagationPort.openDunningCase` now requires nullable `failedPaymentAttemptId`; update host implementations and callers to pass the applied transition's identity.
-Migration: `applyFailedResult` may return `paymentAttemptId?: string | null`; return the durable applied attempt so propagation can forward it, including on replay.
-Migration: managed hosts must pass exact applied-transition attribution to the new overloads. Fresh missing attribution refuses with SQLSTATE `55000`; do not substitute the current or prepared attempt. Already-applied donor schema/backfill requires the explicit host mapping in DATA_AND_MIGRATIONS.
-
-Native attempt-replay parity remains REGISTERED with M10; these managed forwards
-do not implement native parity or authorize host activation.

package/README.md

@@ -10,8 +10,12 @@ Development preview. This package is part of the publishable set with core and o
 
 It holds the runnable server substrate an OpenLup application composes: the Node HTTP runtime, BFF dispatch, scheduling and job leases, blob storage, data gateways, the node-postgres migration runner and bundle composition. Ports and their contracts stay in `@openlup/core/platform-runtime`.
 
-For the prepared `0.28.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0280) before selecting optional services. Experimental
+For the prepared `0.29.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0290) before selecting optional services. Experimental
+M13 marketing uses browser-safe `./marketing`, type-only browser-safe
+`./marketing/contracts`, and Node-only `./marketing/server` and
+`./marketing/server/postgres`. Marketing contributions and bindings remain
+inert and default-off. Experimental
 account/support APIs use `./account-support` and the type-only
 `./account-support/contracts`; reference bindings remain inert and default-off.
 Apply the M12 support-authority forwards after complete same-rail predecessors
@@ -50,7 +54,7 @@ Adopters must not activate unselected or unready invoicing; installation and
 inert contributions register no runner, worker, route or schedule.
 M06 managed-host proof classes remain pending in the
 [M06 parity ledger](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
-Size comparison uses the published `0.27.0` tarball. Preparation and offline
+Size comparison uses the published `0.28.0` tarball. Preparation and offline
 adapter evidence grant no publication or provider-account certification.
 
 Longer module recipes live in the [platform package reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md).
@@ -93,6 +97,12 @@ timestamp used in the webhook's idempotency key.
 | `./inventory` | Experimental schemas/ports, handlers, native stores, projection, injected forecast and SQL descriptor; `./inventory/contracts` DTOs. |
 | `./catalog` | Experimental neutral catalog schemas, drafts, reads, media source packs and publication ports |
 | `./catalog/contracts` | Dependency-free catalog DTOs, media resolver, authority and canonicalization helpers |
+| `./marketing/server` | Node-only acquisition handlers, direct read/evidence factories and research orchestration without `pg`; host responder, authorization, binding and notification copy |
+| `./marketing/server/postgres` | Acquisition case and research evidence PostgreSQL port factories; requires the existing optional `pg` peer |
+| `./marketing/server` (analytics context) | Injected analytics context handler with host persistence, capability and identity bindings |
+| `./marketing`, `./marketing/contracts` | Browser-safe acquisition history, portable prelaunch, survey evidence and newsletter consent schemas; type-only DTOs and acquisition/research ports |
+| `./marketing`, `./marketing/contracts` (analytics) | Browser-safe acquisition and research schemas, injected analytics, paid purchase and consent-time facts; type-only DTOs and ports |
+| `./marketing`, `./marketing/contracts` (SEO and content slots) | Browser-safe JSON-LD serialization and graph builders, URL/hreflang helpers, ordered head data and contact/legal projections; type-only organization, contact, legal-document and privacy-processor content slots |
 | `./commerce`, `./commerce/contracts` | Browser-safe neutral commerce schema cores, generic ports and pure contract helpers |
 | `./commerce/server` | Node-only OMS, returns, native reviews/media and hosted-feedback handlers/adapters and order-detail composition, email consumers, dispatch registry, paid-fulfillment binding and checkout compensation, checkout handlers, runtime and shared paid-order saga |
 | `./pricing` | Experimental price authority, quote computation/handlers, offer projection/cache, readiness and policy tokens |
@@ -103,6 +113,135 @@ timestamp used in the webhook's idempotency key.
 | `./shipping` | Experimental delivery ports, injected-schema handlers, summary/evidence; native flat-rate port + Core schema readiness |
 | `./shipping/contracts` | Type-only delivery, pickup-point, summary and evidence DTOs |
 
+## Marketing contracts
+
+`./marketing` provides acquisition address references, historical case projections,
+list/count reads, portable prelaunch list/detail schemas, idempotency keys, survey submission/evidence/list schemas and
+newsletter consent events/responses. Reference compatibility shims forward the
+same schema objects and load the reference validation wrapper before package
+schemas. The marketing runtime entry configures the shared Zod instance in
+jitless mode before constructing schemas, preserving CSP-safe initialization
+for direct imports as well as reference facades, like the pricing, catalog and
+communications entries. The type-only `./marketing/contracts` entry has no
+runtime initialization. The rich prelaunch DTO and case submit/transition schemas remain application-owned
+and are excluded from the browser entries. The shared
+`acquisitionOpaqueReferenceSchema` lets those retained contracts reuse the exact
+reference syntax. No entry registers a route automatically.
+
+`./marketing/contracts` exports only types. Explicit acquisition DTO shapes are
+checked against the runtime schema inference by an executed TypeScript equality
+witness. Reachable case ports expose list, get, active count and close; the app
+uses the server-only compatibility port for its retired methods. Evidence ports retain survey submission,
+survey listing and consent application. Port types are also forwarded through
+the runtime entry, following the commerce boundary. Both entries forward research schemas or types from the compatibility
+owner, `@openlup/core/marketing/research`; runtime schemas retain object identity.
+Case locale remains `en|pl`, matching the persisted constraint. Widening it requires
+a separate migration. Historical wire values remain unchanged.
+
+The source and built entries have browser graph proofs. The root test runner
+selects `test/marketing/`; the installed consumer checks both public entries,
+compiles typed usage and refuses deep imports. Kiosk and research reference
+contracts/ports continue to consume the core export. The app owns its admin
+response client and host composition.
+
+`./marketing/server` owns acquisition case handlers, list/count and prelaunch
+list/detail factories, survey evidence submit/list and consent application,
+research submit/admin handlers and managed survey orchestration without loading
+`pg`. Select `./marketing/server/postgres` for the two PostgreSQL port factories
+after installing the existing optional `pg` peer. Hosts inject the BFF responder,
+authorization and binding resolvers. Direct case reads receive the host bundle
+predicate at their original guard; prelaunch and evidence dispatch stays in the
+host. Notification HTML and subject are injected separately, preserving
+HTML rendering before the subject clock read. The reference owns retired
+route refusals, raw signed consent ingress and notification copy. PostgreSQL
+SQL, role selection and transaction/pool handling remain unchanged. The
+server-only compatibility command types do not expose retired admission schemas.
+
+Analytics facts share these browser-safe entries. `createNoopAnalytics` implements
+Core's existing analytics port; deployment and advertising defaults remain inert.
+`AnalyticsEventMap<StepName>` retains the host's literal step vocabulary, with
+`string` as the neutral default. Private transport ownership fields and envelopes
+remain host extensions. Types are forwarded type-only by `./marketing/contracts`.
+
+`createAnalyticsDataLayer` owns loader readiness per instance and accepts the host's
+browser/storage access, consent key and change event, `consentSignalNames`, event
+prefix, container reader and deployment callback. `consentSignalNames` supplies
+one `analytics` wire name and the ordered `advertising` wire names. Without it,
+no consent command is pushed and optional event admission returns false, even
+with browser access, a container and stored consent; deployment attempts remain
+independent. Consent commands seed default before update and
+use array-like arguments; advertising grants read marketing consent at push time.
+Revocation denies every signal. Sinks are attempted independently with failure
+isolation and no replay of observations made before consent. Admission booleans
+mean synchronous local acceptance only, never delivery or business acknowledgement.
+
+`createAnalyticsRoutePolicy` requires public paths, redirect sources and all
+sensitive-path sets. Its optional-route predicate preserves broad eligibility;
+deployment URL sanitization admits exact public paths and safe campaign values.
+`projectPaidPurchase` consumes only structural paid-recap facts, preserving
+allocation/grouping, the item cap and ordered suppression reasons without an
+ambient currency policy. `selectMarketingHistoricalConsentTime` selects exact
+native chronology only after host authorization, without changing the local
+grant. The reference retains its narrower checkout-kind admission and all wire
+names. [Purchase equivalence](../../src/checkout/machine/purchasePayloadEquivalence.test.ts)
+and the package analytics witnesses pin these boundaries.
+
+`createAnalyticsContextHandler` in `./marketing/server` accepts a required BFF
+responder, enable reader, persistence resolver, access-token reader, trusted-subject
+resolver, capability mint/hash functions, historical cookie name and `clientIdField`.
+The host supplies the client-id wire field name through `clientIdField`; the strict
+request also keeps `granted` and `explicitGrant`. Grants require a client
+id and existing revoked contexts require an explicit new grant for replacement.
+Only token hashes reach persistence. Enrollment uses only the server-verified
+subject, and invalid bearer grants refuse before writes. Cookie attributes and
+method/flag/origin/schema refusal order are preserved. The host owns flag and
+RPC names, gateway authority, route mounting and observability. Persistence
+operations must reject on failure; null persistence refuses as unavailable.
+There is no default persistence, portable SQL or reference route for this handler.
+An `active` result is a local context fact, never delivery, and telemetry context
+failure never gates commerce. The [context witness](test/marketing/analyticsContext.test.ts)
+exercises the factory through synthetic host bindings.
+
+`./marketing` also provides browser-safe JSON-LD serialization and graph builders,
+route URL/hreflang helpers, an ordered head descriptor and plain contact/legal
+projections. Applications supply identity, origin, routes, locales, images and
+content; the descriptor is plain data for a host head manager. The type-only
+`./marketing/contracts` entry exports shared organization facts and contact,
+legal-document and privacy-processor shapes, also forwarded as types by the
+runtime entry. The package supplies no document wording, processor inventory or
+content policy. The [marketing recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#marketing-seo-and-content-slots)
+owns the mechanics and installed-artifact proof.
+
+## Marketing composition
+
+`./composition` exports `createMarketingContribution`, an inert descriptor for
+the `marketing` capability's `./marketing`, `./marketing/contracts` and
+`./marketing/server` entries, with a runtime dependency on `identity/contracts`
+for obligation validation.
+Supply already-bound operations and host schema requirements. Ports, routes and
+triggers share the supplied functions; null ports remain required for Core
+readiness, and handlers retain only registration descriptors. Duplicate handler,
+schedule or route identities refuse. Construction invokes no callable and
+installs no worker, route or schedule. See the
+[composition contract](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#contributions-seams-and-readiness)
+for the host admission boundary.
+
+`./marketing/server` also exports `createMarketingPrivacyContributor` and
+`createMarketingPrivacyBindings`. Explicit enablement and both complete owner
+ports select one contributor; its `exportPersonalData`, `assessErasure` and
+`eraseOrRetain` callables can be passed directly to `createMarketingContribution`.
+Missing ownership makes coverage unavailable and erasure unresolved. Identity
+owns assessment ordering, subscription vetoes, receipt replay and transaction
+rollback; the marketing fence runs only during `eraseOrRetain`. Provider request
+acceptance never proves deletion. The reference leaves marketing unselected,
+so its marketing privacy coverage remains an open gap. See the
+[privacy composition recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#marketing-server-composition).
+
+The contributor and binding declarations use identity contract types and local
+structural interfaces compatible with identity's `PersonalDataContributor`.
+They do not reference identity's main entry; `./marketing/server` compiles without
+`pg` or `@types/pg`. Select `./marketing/server/postgres` explicitly for those ports.
+
 ## Commerce contracts
 
 `./composition` exports the inert `createCommerceContribution` for the installed
@@ -256,7 +395,7 @@ SQL (class (b) retention): native uses 14 days and the contributed managed profi
 uses 21 days. There is no TypeScript delay parameter or SQL change.
 The reference browser contract facades initialize their shared Zod instance in
 jitless mode before loading package schemas, preserving CSP-safe construction.
-The package contracts add no global Zod configuration side effect. Browser
+The commerce package contracts add no global Zod configuration side effect. Browser
 conformance bundles the complete commerce entry and both reference facades
 without externals; the raw-upload source is a failing browser control, while
 the complete server entry bundles for Node.

package/dist/composition/index.d.ts

@@ -8,3 +8,4 @@ export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
 export { createCommerceContribution } from "./commerceContribution.js";
 export { createAccountSupportContribution } from "./accountSupportContribution.js";
+export { createMarketingContribution } from "./marketingContribution.js";

package/dist/composition/index.js

@@ -9,3 +9,4 @@ export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
 export { createCommerceContribution } from "./commerceContribution.js";
 export { createAccountSupportContribution } from "./accountSupportContribution.js";
+export { createMarketingContribution } from "./marketingContribution.js";

package/dist/composition/marketingContribution.d.ts

@@ -0,0 +1,21 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Describe existing selected marketing callables; never install another executor. */
+export declare function createMarketingContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    marketing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+    handlers: Contribution["handlers"];
+    schedules: Contribution["schedules"];
+    routes: Contribution["routes"];
+}): {
+    contributions: Contribution[];
+    ports: {
+        [k: string]: ((...args: never[]) => unknown) | null;
+    };
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+    triggers: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};

package/dist/composition/marketingContribution.js

@@ -0,0 +1,29 @@
+/** Describe existing selected marketing callables; never install another executor. */
+export function createMarketingContribution(input) {
+    for (const [kind, names] of [
+        ["handler", input.handlers.map(handler => handler.eventType)],
+        ["schedule", input.schedules.map(schedule => schedule.id)],
+        ["route", input.routes.map(route => route.id)],
+    ]) {
+        if (new Set(names).size !== names.length)
+            throw new Error(`marketing_duplicate_${kind}`);
+    }
+    const contribution = {
+        manifest: {
+            name: "@openlup/platform", version: input.version, kind: "rail",
+            module: { id: "marketing", kind: "capability", provides: ["./marketing", "./marketing/contracts", "./marketing/server"],
+                // The server entry validates obligations with identity's runtime contract schema.
+                dependsOn: [{ module: "identity", entries: ["./identity/contracts"] }] },
+            emits: [], handles: input.handlers.map(handler => handler.eventType),
+            schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), env: [],
+            requiredPorts: Object.keys(input.marketing), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+        },
+        handlers: input.handlers.map(({ eventType, timeoutMs }) => Object.freeze({ eventType, timeoutMs })), schedules: input.schedules, routes: input.routes,
+    };
+    return {
+        contributions: [contribution],
+        ports: Object.fromEntries(Object.entries(input.marketing).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/marketing:${name}`, fn])),
+        routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/marketing:${route.id}`, route.handle])),
+        triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/marketing:${schedule.id}`, schedule.run])),
+    };
+}

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>;