@openlup/platform 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -4,10 +4,71 @@ Notable changes to this public-source workspace package are recorded here.
 “Unreleased” means no npm version carries the change yet; immutable OpenLup
 source previews may already ship some changes, and their release notes say
 which. Declaration snapshots track candidate drift, not a stable API or
-SemVer promise.
+SemVer promise. This file keeps the current release and the two previous ones;
+earlier releases are recorded verbatim in `packages/platform/CHANGELOG-HISTORY.md`
+in the source repository.
 
 ## [Unreleased]
 
+## [0.21.0]
+
+- Publishable on the npm `latest` dist-tag as `0.21.0`, from tag
+  `openlup-platform-v0.21.0`.
+- Preview set: core/outbox unchanged, UI private `0.0.0`; published `0.20.0` size baselines, unchanged caps.
+
+### Cumulative M07 status: payment truth and repair surfaces complete for this wave
+
+- Experimental payments/contracts/runtime: unchanged prepared ordering; neutral execution/evidence/readback/conformance, verified truth, first-receipt ingress, method lifecycle/reconciliation; host-owned persistence, translation/failure policy.
+- Native PostgreSQL truth/settlement/later-only alignment; three unchanged sparse SQL projections, not an install chain. Refunds never cancel subscriptions.
+- Repair/recovery/buyer verify inject rail capabilities; unknown rails refuse. Reference BFF retains mapping/schemas/ownership/auth order/transient callbacks. Browser/verify outcomes never prove payment success.
+- Reference-application source (no new export), opt-in repair view: `commerce/paymentStatusClient`, `commerce/paymentVerifyClient`, `payment/components/PaymentStatusPoller`; stored paid alone confirms, redirects require HTTPS, collection/confirmation stay injected, unsupported setup is visible. Exact file/specifier guards refuse broad commerce/operator clients; source-import proof keeps default view unmounted.
+- Truth services/one optional named binder use the host executor, no new schedule/executor. Selectors default-off: nothing activates by default. First-insert adapter fingerprint excludes receipt time/audit.
+- Two experimental example adapter subpaths under `./payments/`, named in the README. Card-processor example: three frozen exports, injected host client/neutral ports; refund creation, split authorization/capture and exact absence unavailable; cancellation needs host support.
+- Regional-processor example: host I/O, Model O aliases, verified observations, purpose-sensitive readback; check certificate validity/notification freshness. Both examples have no import I/O/default binding and await account TEST evidence.
+- Example adapter advisory: mismatched nonzero refusal money stays unknown/manual; trusted document refusals mean customer data correction; configuration mismatches throw before I/O. Unpaid/transient no-dispatch classifications unchanged.
+- Settling money missing/invalid/non-positive or blank currency refuses as amount mismatch; conformance requires positive money. Empty optional transients stop false leak refusals; JSON-escaped transients in diagnostics/readbacks/stored payloads and payer contact in execution results now refuse.
+- Private types reuse canonical money/attempts; unused imports removed, runtime/API unchanged.
+
+Migration: upgrade all `@openlup/*` `0.20.0` → `0.21.0` for exact pins. No schema migration; install the canonical catalogue, not sparse projections. Attempts add optional method selection/transient payer contact; contact is dispatch-only, never persisted/audited/logged/diagnosed. Missing adapter-required input requires exact before-dispatch `notDispatched`. Registration refs/kind/status require host `resolveMethodOwner` client/subscription ownership or are omitted. Lifecycle/normalized nested audit copies typed fields only; conformance scans all for secrets/contact. Adapter-filtered redacted audit never stores raw bodies; typed evidence overrides reader facts, audit bag fills untyped facts; identity/fingerprint exclude bag/receipt time. Other changes need no migration, and nothing rewires a host automatically.
+
+Migration: F2 replaces assumed full refund with `require-evidence`: missing/null kind/amount/operation identity is durably recorded/acknowledged, not applied. Supply original money, stable operation identity and cumulative snapshot, event delta or explicit full reversal (`refund`/`chargeback`); full evidence stays valid. Former default needs `refundEvidencePolicy: "legacy-assume-full"`, also in the reference handler; no native parity implied.
+
+Migration: D11 changes every caller of the reference payment control port (the selected verified ingress, the existing provider webhook handler and the captured reference checkout): apply/post-process redelivery using the first stored receipt instant, not redelivery time, so it cannot shift the cycle again. Replay reads winning receipt evidence and refuses (503) when that instant is unavailable. A legacy pre-fingerprint row takes the later clock once. Retain receipt evidence on upgrade; provider routes are not switched to opt-in ingress.
+
+### Known limitations
+
+- Portable dunning repair has no managed twin: exhaustion still pauses active subscriptions there; retaining active status needs a managed forward.
+- D8-1: native advisory v2 promo-code candidates/rejection details unavailable.
+- D8-2: native mounted v2 issue/honor/fallback unavailable.
+- D8-3: native acquisition-only mounted issuance/honor unavailable.
+- D8-4: full native/managed eligibility equivalence unavailable.
+- Bundle-1: independent DB human-only actor-kind enforcement absent natively; first in the native-backend parity round.
+- Bundle-2: managed-equivalent actor-kind/email history absent natively.
+- Bundle-3 closes injected-reader M05 mounted admin/feed readback only. Native new-purchase stock read absent despite P5a installed-store proof; deferred second after bundle-1 (owner 2026-10-21); readiness refuses.
+- Bundle-4: incumbent real-PostgreSQL contention only; no exactly-once guarantee.
+- Managed schema/pgTAP retain `44.404`; removal needs owner decision/forward; reference composition supplies it to app code.
+- A1 offline only; account/hosted-time/owner TEST evidence unclaimed; `communications/klaviyo` verification-pending.
+- M05 omitted opt-ins preserve defaults/outputs/read order/schedules/refusals/acceptance-token bytes/SQL.
+- Native inventory adjustment unavailable; address writes refuse readiness. Flat-rate save needs selected port/Core readiness/applied-seed observation.
+- Native shipping audit unavailable; handler swallows best-effort audit failure.
+- Native flat-rate integer bounds (0 through host maximum; reference 100,000 minor units) use request schema, not DB CHECK.
+- Managed ATP/forecast/dated-supply/pagination readback unproved/pending M06.
+- Managed two-session locks/concurrency/uncovered compensation unproved/pending M06.
+- Managed exact-prefix upgrade/ledger unproved/pending M06.
+- Managed address idempotency/conflict/readback unproved/pending M06.
+- Managed successful flat-rate read/save unproved/pending host authority.
+- M06 stock-wait lifecycle/durable timing/staging controls retain C5/C6; busy/try-gate, continuity/flag/TTL transfers are dispositions, not PASS.
+- Shipping national-registry fields/locale-specific `canonicalAddressKey` fold await M16 host market pack/key migration; reference shipping copy stays locale-specific until M16.
+- Native durable prepared storage, method setup, absence reopen and cumulative refunds unavailable; no production installation parity claimed.
+- Typed refusal-envelope forwarding unavailable (`failureReason` only); reusable registration needs host ownership resolution.
+- Incomplete chargebacks stay refunds/unapplied: reclassification bypasses evidence validation into dispute apply; limited operator recovery.
+- Audit compatibility still detects `chargeId`; refund operation identity/original money supply no typed charge identity.
+- M07 follow-up: repair poll can clear host redirect; post-timeout verify never restarts polling; unlocalized poller; fixture builds/never calls handler.
+- M07 follow-up: reference status route wrong-rail witness.
+- M07 follow-up: explicit reference-route refusal for unsupported method setup.
+- M07 follow-up: deployment-neutral disabled-verify reason.
+- M07 follow-up: reference card normalizer missing-amount path; package settling evidence already requires positive money.
+
 ## [0.20.0]
 
 - Publishable on the npm `latest` dist-tag as `0.20.0`, from tag
@@ -153,233 +214,3 @@ Question (2026-10-21): "The platform package's root docs (README + CHANGELOG) wi
 Owner's answer: "Raise to 49,152 B (Recommended)"
 Option description shown to the owner: "Same figure as core. Unblocks the next few releases; the CHANGELOG grows every release, so this cap would otherwise block each one."
 Recorded as an owner decision taken through the coordinator's question on 2026-10-21.
-
-## [0.18.0]
-
-- Publishable on the npm `latest` dist-tag as `0.18.0`, from tag
-  `openlup-platform-v0.18.0`.
-
-- M06 P4: retain named compatibility shims, restrict inventory smoke evidence to package-owned tests, neutralize synthetic transport fixtures and clarify inventory documentation; no runtime or API change.
-
-### 0.17.0 → 0.18.0 set scope
-
-- Prepare the complete development-preview set at `0.18.0`: core and outbox are
-  unchanged republications; platform includes every change on main in this set.
-- M05 adds catalog foundation/contracts, draft validation, product/lifecycle DTOs,
-  authority/GTIN/quantity helpers, media and source-pack operations,
-  fixed-bundle read/admin/feed logic, native envelope/draft stores and an inert
-  catalog contribution; pricing adds the neutral quote foundation, authority,
-  subscription policy and assignment token, quote/offer projection, opt-in
-  acquisition terms and promise consent; promotions includes advisory, preview, acceptance,
-  admin/native reads and sweep with explicit host bindings; lifecycle/publication
-  contracts alone do not provide a publisher or native lifecycle writes.
-- M05 P6: pricing and bundle comments are corrected, VAT arithmetic delegates to the
-  existing helper and moved test fixtures are neutral with assertions unchanged;
-  no API change.
-- Reference-application source: opt-in catalog, product, basket, builder and admin UI consumes explicit
-  data/locale/media/lifecycle inputs; basket edits invalidate promise consent and
-  minor-money display uses the currency exponent.
-- Shipped catalog SQL projects unchanged canonical positions 1/8/16/19/58/59/61,
-  promotions projects 47/48 and inventory projects 27/33; native catalog factories
-  retain the existing store bodies and references preserve their named exports.
-- A1 adds 17 neutral marketing/consent declarations, the three-function `communications/resend`
-  entry, the `communications/klaviyo` marketing adapter and lazy opt-in reference bindings with
-  invocation-time admission; default routes, schedules and handlers stay empty.
-  Existing providers remain assignable; existing neutral entries keep their runtime
-  behaviour (the declarations above are additive), and the maintained reference
-  adapter and default wiring are unchanged.
-  Authenticated raw webhooks and GET-only delivery reconciliation retain host
-  ownership of persistence and admission; no SDK or default sender is added.
-  `communications/klaviyo` profile projection, negative consent readback,
-  account-wide deletion acknowledgement and authoritative consent push stay
-  verification-pending until the host supplies owner TEST verification.
-  Audience-scoped deletion and deletion status are unsupported; newsletter sync
-  refuses. No flow control, historical import, suppression edits or automatic
-  mutation retry is added.
-- Consent push grants stay audience-scoped; only withdrawals may be account-wide.
-  The capability declares `grantEffect`; accepted/acknowledged results require
-  `reconcileRequired`. Conformance keeps grants unsettled until settlement and
-  fresh readback. Withdrawals bypass grant-caused fences/quarantine but retain
-  same-key withdrawal fences and account cooling. No push factory, activation,
-  callback, retry or subpath is added.
-- M06 in progress: inventory and shipping entries are early surfaces; module not complete
-- The merged M06 surfaces include inventory contracts/admin/native reads, injected
-  new-purchase availability, reservation policy/maintenance and dated forecast
-  calculation with required provider injection, plus shipping selection, address
-  and rate handlers with required host validation.
-- @openlup/platform size growth: added M05 catalog, pricing and promotions implementations, native stores and SQL projections, A1 communications adapters and consent contracts, and the merged early M06 inventory/shipping surfaces with their declarations and documentation.
-
-Migration: upgrade the entire `@openlup/*` set from `0.17.0` to `0.18.0` for exact
-core peer pins; new module adoption remains explicit and experimental.
-Catalog and promotions server entries are adapters: their declarations require
-selected optional `pg` peers, while runtime imports and injected executors work
-without them and their contracts entries remain non-adapters. Supply host schemas, authorization,
-responders and policies through the documented bindings. Acquisition requires
-an explicit `AcquisitionFinancialPolicy` with no default; absence refuses with
-`acquisition_terms_policy_unconfigured`, and reference activation remains off.
-Bind resolved terms from the final optional issue/honor callback argument for
-acquisition-aware acceptance; existing callbacks remain assignable. Stop
-assigning `NegativeFeedback.kind` or `.outcome`, now readonly. Reference-application
-source threshold classifiers require the host's explicit threshold. Generated enum declaration
-ordering changes preserve member values and runtime behavior. Catalog adds
-`createPostgresBundleCatalogStore`, `createPostgresCatalogDraftStore` and
-`createPostgresCatalogSkuEnvelopeReadPort`, plus `BUNDLE_MIGRATIONS` (16/19) and
-`CATALOG_MIGRATIONS` (1/8/58/59/61); composition adds
-`createCatalogContribution` and `CatalogContributionInput`, with no public export
-removed or renamed. Existing named reference imports remain compatibility paths.
-The native writer, pooled transaction binding and transport remain reference-owned;
-browser schemas stay local. Core remains the promotions evaluator; no claim writer
-is added, and claim writing and mounted acceptance retain their owners. Reference
-shipping selection, pickup and stock UI mechanics and browser validation stay local.
-Install the complete canonical migration manifest, never sparse package SQL
-projections as an installation chain; this preparation adds no new SQL migration.
-A1 hosts retain credentials, identity/authority, atomic storage, environment,
-egress and schedule ownership; acknowledged/accepted does not establish remote
-effect and local consent remains authoritative.
-
-### Known limitations
-
-- D8-1: native advisory v2 promo-code candidates and rejection details are not supported on the native backend.
-- D8-2: native mounted v2 code issue/honor/fallback is not supported on the native backend.
-- D8-3: acquisition-only mounted issuance/honor is not supported on the native backend.
-- D8-4: full native/managed eligibility equivalence is not supported on the native backend.
-- Bundle-1: independent database human-only actor-kind enforcement is not supported on the native backend and is the first item of a future native-backend parity round.
-- Bundle-2: managed-equivalent actor-kind/email history is not supported on the native backend.
-- Bundle-3 is closed for M05 mounted admin/feed readback through the merged availability builder with an injected stock reader; the real native stock read remains M06 P5a work.
-- Bundle-4 establishes only incumbent real-PostgreSQL contention characterization and provides no exactly-once guarantee.
-- The managed baseline schema and its pgTAP tests retain the incumbent legacy value `44.404`; removing it needs a forward migration and an owner decision, while reference composition supplies that value to application code.
-- A1 evidence is offline only: account verification, hosted-time behaviour and owner TEST certification are not claimed, and the `communications/klaviyo` adapter's capabilities stay verification-pending.
-
-## [0.17.0]
-
-- Publishable on the npm `latest` dist-tag as `0.17.0`, from tag
-  `openlup-platform-v0.17.0`.
-
-- Add experimental `./communications` and browser-safe
-  `./communications/contracts`, plus generic capped raw-body, hex-HMAC and
-  constant-time comparison helpers in the existing `./http` entry. Compose neutral
-  transport/results/capture, rendering/content, independent Auth verification,
-  receipt/observation, polling/reconciliation, consent and membership sync engines.
-  Provider clients, protocol/key mapping, copy and activation remain host-owned.
-- Require explicit egress admission for supported injected network senders.
-  Guarded transports validate fresh host decisions, redirect sink sends and
-  suppress drops before network entry; provider names grant no admission.
-  Capture remains local acceptance. Preserve the maintained reference transport
-  through its trusted composition bridge and keep Auth/provider verification separate.
-- Add Polish/English invoice, role, opt-out and inquiry default-content factories
-  with whole-copy injection. Preserve implicit Polish invoice and existing role
-  expectations; EN invoice is construction-time opt-in. Reference opt-out page
-  copy, EN legacy/error text, document language and escaping change deliberately.
-  Pure inquiry rendering activates no sender. See the
-  [B1/B2 expectation inventory](../../docs/platform/plans/oss-m04-communications-triggers.md#b1-egress-boundary).
-- Add an opt-in immutable composition-time purpose registry with mandatory
-  classification and finite legacy defaults. Registration grants no consent,
-  provider activation or managed schema permission; custom-purpose persistence
-  stays with the host. Add neutral newsletter processing and marketing ports
-  without a runner or a new public purpose.
-- Add four bounded native store groups: delivery observation/readback, existing-rail
-  membership sync, operator notification recipients and durable consent decisions.
-  Append CREATE-only direct catalogue position 70,
-  `20261019200000_communications_native_operations.sql`, and its exact sparse
-  projection. Standard factory lanes refuse unsafe effective privileges.
-  Sync uses `public.outbox_events`; the sidecar is not another executor.
-- Compose selected native readback and atomic signed-token preferences with Core
-  readiness, explicit provider/binding identities and host-supplied clocks and
-  schedules. Add distinct opt-in operator evidence and installed substitute-provider
-  proof. Captured, network-accepted and membership-synced are not delivered.
-  Native consent excludes managed 16-hour / 2-day / 4-week caps and legacy
-  contact-touching, and is not a send-time fence. No default cadence, deployment
-  activation, full native general sender or UI package capability is added.
-  [T07 destinations](../../docs/platform/plans/oss-m04-communications-triggers.md#t07-destination-matrix)
-  remain explicitly open with their owning modules.
-- @openlup/platform size growth: added the reviewed neutral communications runtime and browser content contracts, bounded native stores and SQL projection, and their API/adoption documentation.
-
-Migration: `0.16.0` did not export communications. Upgrade the complete package
-set to `0.17.0` for the exact core peers, then explicitly select and bind the new
-experimental capability. Existing non-communications entries retain their contracts.
-The host retains renderer/copy, environment, origin, egress, provider protocol,
-credentials and schedule ownership. The generic HTTP helpers do not replace the
-independent Auth Standard Webhooks or provider-specific verification protocols.
-
-Install the complete selected direct canonical catalogue through position 70
-before selecting native stores. `COMMUNICATIONS_MIGRATIONS` projects positions
-2, 9, 20 and 70; never reapply these sparse files over an existing canonical
-history or treat them as a standalone chain. Preserve managed/private lineage
-and custom-purpose persistence: registering a purpose does not expand managed
-CHECKs. Thread the same registered purpose union and registry through selected
-policy, token, newsletter and store bindings; omitted arguments retain finite
-legacy defaults and existing signing bytes.
-
-`registerNativeSyncWorkInTransaction` is a trusted host transaction seam. Its
-caller-owned executor must already hold the lane's safe effective privileges;
-this function does not check those privileges. The caller owns the transaction
-and must commit or roll back permission, sidecar and existing-rail effects
-atomically. Use a safely admitted lane; the helper grants no provider or claim
-authority. Standard native sync factory transactions check
-`public.communication_native_sync_state`, `public.outbox_events` and
-`public.communication_recipient_consents`.
-
-Custom native stores must provide binding-scoped `findByMessageId`, bounded
-`listEvidence` (1–100) and atomic `registerPreference` as declared by the new
-surface. Supply explicit provider/binding identities and full catalogue admission.
-Hosts preserving older opt-out page bytes retain their own presentation binding;
-token purposes, verification and existing HTTP status/header semantics remain.
-See the [package composition guidance](README.md#communications-import).
-
-Growth reading: +61.4% against the retained initial `0.16.0` baseline (256,973
-packed bytes), measured before S1 notes at 414,808 bytes; final S1 measurements
-are recorded in the programme evidence. No cap is changed. Baseline evidence
-(2026-10-20): the published `0.16.0` tarball is 257,434 packed bytes, SHA256
-`030756175d61279aab0ae7b26b27783e08467ec93673f5623d19d0b7fc436463`.
-S1 option B retains the initial release-gates baseline rather than replacing it
-with this observed registry identity.
-
-## [0.16.0]
-
-- Publishable on the npm `latest` dist-tag as `0.16.0`, from tag
-  `openlup-platform-v0.16.0`.
-
-- Add the experimental identity capability at `./identity` and browser-safe
-  `./identity/contracts`: role-based authorization, actor-scoped profiles,
-  bounded normalized contact matching, unconfirmed soft accounts with explicit
-  email-trust policies, and configured-origin magic-link redirect resolution.
-- Add operator invitations with transactional pending acceptance, expiry,
-  cancellation and revoked re-invitation for direct stores, and immediate active
-  membership with repeat/concurrent recovery for managed stores. Direct operator
-  login uses single-use email challenges, operator-audience sessions, live
-  membership authorization, explicit first-administrator bootstrap and bounded
-  challenge pruning. An opt-in OIDC access-token verifier provides pinned issuer
-  discovery, bounded rotating JWKS, strict claim validation and deterministic
-  issuer/subject principals for direct composition.
-- Add versioned personal-data contributors, identity export and transactional
-  direct erasure with contributor vetoes, challenge/invitation cleanup,
-  pseudonymization, guarded operator revocation and idempotent receipts. Managed
-  export reports incomplete coverage; managed erasure refuses with
-  `MANAGED_PRIVACY_ERASURE_UNAVAILABLE` without mutation. Issued tokens may remain
-  valid until expiry.
-- Add seven byte-identical identity SQL projections and host-selected module
-  schema readiness. The projections retain canonical migration identities and
-  positions; they are not a standalone installation chain.
-
-Migration: identity adoption is opt-in; upgrade the complete package set together
-for the exact `@openlup/core` `0.16.0` peer pin. Supply the selected bundle's schema
-inventory, clients and delivery bindings, an explicit email-trust policy, exact
-redirect origins, a distinct operator audience and a deployment policy for
-admin, operator and privacy routes. Managed soft-account provisioning requires
-an email-trust envelope with automatic confirmation disabled and all enabled
-non-email providers declared email-verifying. Install the complete direct
-catalogue through `20261018190000_identity_privacy_erasures` before enabling
-identity; never reapply projections to an existing canonical history. Managed
-adopters need their committed chain's
-`20261018160000_identity_service_role_capabilities.sql` forward for contact linking
-and operator membership capabilities, and must supply their own erasure path.
-
-## [0.15.0]
-
-- Publishable on the npm `latest` dist-tag as `0.15.0`, from tag
-  `openlup-platform-v0.15.0`.
-
-- First publication of `@openlup/platform`, the server substrate for an OpenLup application, with one module subpath each for `http`, `bff`, `scheduler`, `blob`, `data`, `migrations`, `job-ledger`, `kernel` and `composition`.
-- Transport-neutral scheduled jobs: a `run(context)` contract, an empty job registry, a lease-aware runner and an authenticated HTTP cron entry, with a constant-time cron secret comparison.
-- Per-capability bundle readiness that refuses an unknown bundle and reports every missing scheduler, lock and blob setting together.
-- Blob capability selection with filesystem, Vercel Blob, Supabase Storage and S3 bindings; `pg`, `@types/pg` and `@aws-sdk/client-s3` are optional peers, and an adapter refuses a missing peer with `OPENLUP_E_PEER_MISSING`.

package/README.md

@@ -4,18 +4,18 @@ 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.20.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0200) before selecting the opt-in M05 parity seams or
-M06 composition bindings. M06 remains incomplete: inventory and shipping entries
+For the prepared `0.21.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0210) before selecting the opt-in M05 parity seams or
+M06 composition bindings, or the M07 payment selectors. M07 payment truth is complete for this wave; its selectors are default-off. M06 remains incomplete: inventory and shipping entries
 are development-preview surfaces, with managed-host proof classes pending in the
 [M06 parity ledger](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
-The size gate compares the prepared `0.20.0` set with the published `0.19.0` tarball;
+The size gate compares the prepared `0.21.0` set with the published `0.20.0` tarball;
 preparation, offline adapter evidence and a passing size cap grant no publication
 or provider-account certification.
 
 ## Package surface
 
-`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its twenty-five experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
+`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
 
 | Export | Contents |
 | --- | --- |
@@ -32,6 +32,9 @@ or provider-account certification.
 | `./identity/contracts` | Experimental capability: browser-safe customer auth port, value types and provider parser |
 | `./communications` | Experimental existing public consent/status, newsletter sync, Auth email hook, transport contracts/capture, observation/polling orchestration, standard webhook verification and delivery receipts; host-selected rendering, egress, protocol mapping and control policy |
 | `./communications/contracts` | Pure renderer, block builders, copy-injected commerce/subscription factories and email/newsletter/Auth/intake/receipt types; no Zod, Node or provider runtime imports |
+| `./payments/stripe` | Opt-in Node payment example with an injected structural client, verified observations and purpose-sensitive readback; no SDK dependency or default activation. |
+| `./payments/tpay` | Opt-in Node payment example with injected HTTP/certificate I/O, Model O aliases and verified observations; no default activation. |
+| `./payments` | Experimental prepared-attempt ordering with injected persistence, execution and failure policy; contracts at `./payments/contracts`. |
 | `./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 |
@@ -771,7 +774,7 @@ for both-bundle commands, the committed managed grants and installation limits.
 
 ## Communications import
 
-For adoption from `0.16.0`, follow the [0.17.0 Migration guidance](CHANGELOG.md#0170)
+For adoption from `0.16.0`, follow the [0.17.0 Migration guidance](CHANGELOG-HISTORY.md#0170) (source repository)
 for the complete package set, canonical SQL installation and host-owned bindings.
 
 M04 P1 relocates the existing public implementation without changing its reference
@@ -1052,3 +1055,166 @@ opt-in browser profile adds no npm entry or UI package export.
 Source contributors record notable changes in package changelog fragments;
 release preparation assembles the shipped CHANGELOG. Follow the
 [public contribution guide](https://github.com/openlup/openlup/blob/main/CONTRIBUTING.md#development-preview-checks).
+
+## Payments prepared attempts
+
+`@openlup/platform/payments` exports `executePreparedAttemptMechanism`: validate before durable preparation, refuse prepared replay, dispatch once unless the host proves no charge, and retry one immutable local finalization. The host owns keys, fingerprints, nominal error trust and persistence. An unknown execution never authorizes redispatch. The reference facade retains its existing binding.
+
+`./payments/contracts` is type-only: execution/dispatch, transient method handoff, capability overlay, verified money/method evidence, bounded readback/absence, neutral refusals, refund observations and multi-subject conformance fixtures. Verification uses receipt time for freshness; ingress starts processing at receipt time and reuses durable first receipt on redelivery. Event identity includes outcome class. Transient authorization and opaque handoffs never enter persisted diagnostics. Capability support is explicit; timeout/truncation is unknown, never exact absence. Refunds require explicit evidence by default; `legacy-assume-full` is an explicit host opt-in. See the [M07 ledger](../../docs/platform/plans/oss-m07-payments-money-truth.md).
+
+The payments entry also exports verified ingress, canonical truth fingerprints, method lifecycle/refusal handoff, reconciliation/verify-now and three runner-independent conformance functions. A new internal boundary projects verified envelopes into the contributed processing carrier: original bytes reach verification unchanged, receipt time starts processing, and durable first receipt overrides redelivery time. Full-reversal chargebacks use the existing dispute path. Snapshot and delta observations preserve original payment money; missing observation, required money or identity refuses before terminal application. Missing money, amounts that are not safe positive integers, or blank currencies on succeeded, refunded or disputed adapter evidence use the existing amount-mismatch refusal before ingestion or terminal application; ingress returns the existing processing-failure response. Failed and pending evidence may still omit money. Hosts own durable stores and response transport. Conformance requires safe positive integer amounts and nonblank currencies on settling money and checks exact identity/money, capability/port agreement and transient-secret exclusion; its evidence contains no handoff. Real-store durability still requires a selected-store proof.
+
+`createPostgresPaymentTruthPort` accepts the platform data executor structural
+shape and `PostgresPaymentTruthOptions` from the contracts entry. It preserves
+the native truth ingest, reconciliation, sweep and readback SQL. `PAYMENT_MIGRATIONS`
+projects canonical units 10/35/56 byte for byte, with path, position, SHA-256 and
+asset URL; install the complete catalogue, never those three files alone.
+`paymentSchemaDescriptor` admits direct truth, settlement and later-only cycle
+alignment, and explicitly refuses prepared durable storage, method setup,
+absence reopen and cumulative refund. Refunds are purely financial. Seven real
+PostgreSQL cases cover fresh/prefix installs, replay/conflict, unknown readback,
+lost acknowledgement, rollback, denied access, dunning/recovery, concurrency and
+later-only dates; this does not claim managed-store parity or host activation.
+
+Attempt input adds optional method selection with opaque, persistable channelRef
+and transient payer email/name. Payer contact is dispatch-only: never persist,
+audit, log or diagnose it. Missing adapter-required input must refuse before
+dispatch with exact `notDispatched` evidence. Conformance scans the execution
+and complete projected stored payload for transient values. Nested normalized
+evidence copies only declared typed fields, including nested facts; unknown
+extra properties are excluded. Incomplete chargeback evidence remains stored as
+a refund and unapplied, a declared operator recovery limit: reclassification
+would apply the donor dispute path without checking completeness.
+
+`createCheckoutActivePaymentActionResolver` authorizes the exact owner, order,
+intent, attempt and execution rail, reads the provider once, then rechecks the
+complete canonical attempt. Hosts inject synchronous `railHandoffKinds` from
+adapter capture capabilities; an unknown rail supplies an empty list. Actions
+carry the provider address and the existing transient `PaymentMethodHandoff`.
+Pending evidence alone may expose a handoff; terminal, mismatched, unknown or
+raced evidence refuses it. `createCheckoutRecoveryPaymentResolver` preserves
+paid/retry/resume/wait/manual-review ordering without creating a new obligation.
+`createCommercePaymentVerifyHandler` validates the existing identity triple,
+checks stored ownership before readback, and uses the shared HTTP/responder
+contracts. A host may inject its responder to preserve request references.
+
+`PaymentRepairMethodPort` collects a method only; it grants no token redemption,
+subscription change or payment success. Unsupported setup is explicit. Method
+evidence may carry neutral registration refs/kind/status. Ingress projects them
+only with `resolveMethodOwner` supplied by the host; adapter-supplied client or
+subscription fields never confer ownership. Without host ownership resolution,
+registration is not projected. Lifecycle carriers copy typed facts only.
+The existing refusal handoff accepts a failure-reason string, not a typed
+adapter refusal envelope; envelope forwarding remains unsupported.
+
+### Payment service composition
+
+`createPaymentServices` accepts `PaymentServicesOptions` and returns
+`PaymentServices` or null when truth schema/capability is unavailable. The host
+supplies `openTruth`, which opens one port and its asynchronous close operation.
+`run` closes that scope after success or failure. Construction performs no I/O.
+Use the existing `createBundleComposer` payments binder for named registration;
+omitting it leaves the host cold. Schema declarations do not prove installation:
+retain the existing readiness/schema checks before admitting work. Existing jobs
+and routes keep their owners; this binding adds no schedule or event handler.
+
+The reference direct truth binding injects its existing executor, templates and
+recovery path. The separate verified-ingress selector is explicit and default-off;
+unknown selections refuse. Its projected carrier includes the adapter fingerprint,
+so the reference store records stable identity on the first receipt independently
+of audit payload or clock. On replay the store reads the first stored instant;
+application and follow-up work reuse it. Missing durable clock evidence refuses
+rather than advancing a cycle. This D11 behaviour change does not mount a provider
+route or enable an adapter; hosts must explicitly wire the selected ingress.
+
+### Opt-in payment example
+
+Import `createStripePaymentAdapter`, `type StripePaymentAdapterConfig` and
+`stripePaymentCapabilities` from `@openlup/platform/payments/stripe`. Supply a
+structural client, `webhookSigningSecrets`, explicit `mode`, required
+`supportedCurrencies` (a non-empty list of upper-case three-letter codes) and optionally
+`toleranceSeconds` (default 300) and `clock` (UTC seconds). The host constructs
+and configures the SDK, associates saved methods with customers and confirms
+off-session requests. Interactive methods follow the declared card/wallet offer.
+Importing creates no I/O or default binding. The adapter advertises the host
+currency list as a frozen copy; the frozen exported descriptor keeps an empty list.
+Account-specific readiness remains pending TEST verification. Exact absence,
+refund creation and split authorization/capture are unsupported. Cancellation
+is enabled only when the injected client supplies it. See the
+[A2 ledger](../../docs/platform/plans/oss-a2-payment-adapters.md) for the current
+preview boundary and the host's responsibilities.
+
+Verified dispute events retain their distinct money outcome and original payment
+identity. Audit payloads carry only donor-filtered facts: the source event type,
+refund charge snapshot and failure-evidence provenance when present. They exclude
+raw bodies, client handoffs and customer authorization and do not affect event
+IDs or fingerprints. The offline adapter conformance witness uses two distinct
+intents and attempts with separate money and provider references.
+
+Method evidence carries the donor lifecycle and replacement facts through M07
+projection when provider time is present. Without provider time it retains the
+method outcome and omits the lifecycle instead of inventing a transition time.
+
+### Opt-in bank and code payment example
+
+Import `createTpayPaymentAdapter`, `type TpayPaymentAdapterConfig` and
+`tpayPaymentCapabilities` from `@openlup/platform/payments/tpay`. Supply `http`
+with explicit `baseUrl`, `clientId`, `clientSecret`, `fetchImpl` and optional
+`timeoutMs`; `urls` with `notificationUrl`, `successUrl`, `errorUrl`;
+`modelOActivationEnabled`, `mode`, and optional UTC-seconds `clock`.
+`notification` requires `rootCertificatePem`, `allowedCertificateUrlPrefix`
+(HTTPS directory ending in `/`) and `resolveCertificate`. The resolver owns
+redirect/egress policy. Both certificates must be valid at verification time.
+
+Verify certificate validity and notification freshness using original raw bytes.
+A signed protected-header `iat` supplies UTC-seconds provider time; absent time
+stays null. `maxNotificationAgeSeconds` defaults to seven days, a generous
+assumption pending confirmation of the provider retry schedule. Signed issue time
+more than `maxClockSkewSeconds` (default 300) after receipt refuses as stale;
+both freshness limits must be finite and nonnegative. Host dedupe
+uses exact event identity plus stable fingerprint when time is absent. The age
+and future-skew limits apply only when the signed header carries a provider issue time. Receipt
+time is used only for freshness. Transaction identity includes outcome class;
+method identity includes event/alias plus outcome.
+
+Bank redirects, one-time codes and unattended Model O alias charges are supported
+when the host supplies the M07 P3 contract payer and method selection inputs.
+Supply transient `payer: { email, name? }` on every
+attempt, including renewals. An omitted or blank name uses the donor
+neutral display label `Customer`. Select `methodSelection: { family: "bank-redirect",
+channelRef }` for the bank channel, or `{ family: "one-time-code" }` with
+`customerAuthorization` as a `TransientSecret`. A `renewal-unattended` attempt
+uses `storedMethod.reference` and its Model O mandate. Missing payer/channel/code
+and Model M or unknown mandates refuse before any dispatch with neutral
+data-correction evidence. Payer and authorization never cross the return boundary
+in diagnostics or request/response payloads. Readback uses the returned API
+transaction ID; notification titles remain distinct. The donor's typed no-charge
+errors return an exact `notDispatched` envelope: proven request-document refusals
+require customer data correction; OAuth, encoding and exhausted pre-send deadlines
+remain transient retryable refusals. Host mode/purpose/currency mismatches throw before I/O.
+A renewal the provider refuses for data validation is classified as needing customer data correction: the host should prompt the customer to update payment details, and the bundled retry schedule keeps its normal retries unless the host treats that class as terminating. The subscription stays active; nothing is paused or suspended by this classification. The contributed adopter applies this classification only when reopening a checkout; the example applies it to every purpose.
+Every other execution error propagates unchanged as ambiguous.
+
+The exported capability descriptor and its nested records and arrays are frozen.
+Currencyless money notifications preserve the paid amount and bind to the adapter's single declared currency; multiple declared currencies refuse as malformed.
+Alias method evidence preserves the donor lifecycle through M07 projection with
+signed provider time; absent provider time leaves the lifecycle field omitted.
+The adapter offers its declared market currency; alias registration and recurring
+cards are not offered by this factory. Account offers
+remain `verification_pending` until owner TEST readback. Chargeback observations carry full reversal,
+original money and stable operation identity; refunded/chargeback readback stays
+unknown for manual review, including historical attempt/error refusals in either
+readback purpose. Pending and refused readback report validated configured money,
+including when the paid amount is zero or absent; a refused result with mismatched
+nonzero paid money stays unknown for manual review. Succeeded readback requires the donor's
+observed paid amount to equal expected money; underpayment and overpayment remain
+unknown for manual review. There is no close or exact-absence port. Refund
+creation and authorization/capture separation are unsupported. See the
+[A2 ledger](../../docs/platform/plans/oss-a2-payment-adapters.md#o-p2-boundary-and-named-deltas).
+
+Verified audit payloads retain only donor-filtered transaction and alias facts,
+including `eventKind`, alias `event` and `aliasType` when supplied. Missing failure
+provenance and failure prose stay absent. Payer, authorization, certificates and
+raw bodies never enter the evidence; audit facts do not affect event identity or
+fingerprints. The offline M07 P2 conformance witness uses two distinct intents,
+attempts, amounts and provider references, with replay and refusal boundaries.

package/dist/composition/composeBundle.d.ts

@@ -1,7 +1,11 @@
 import type { AnalyticsPort, BlobStoragePort, DataGatewayPort, HttpRuntimePort, MigrationRunnerPort, SchedulerPort, TransactionalRuntimePort } from "@openlup/core/platform-runtime";
 import { type PlatformBundleDescriptor, type PlatformBundleId } from "../kernel/index.js";
+interface PaymentServices {
+    run<T>(work: (port: unknown) => Promise<T>): Promise<T>;
+}
 type Env = Record<string, string | undefined>;
 export interface PlatformBundlePorts {
+    payments?: PaymentServices | null;
     http: HttpRuntimePort | null;
     scheduler: SchedulerPort | null;
     blob: BlobStoragePort | null;
@@ -21,6 +25,8 @@ export interface PlatformBundle {
  * transactional binder also receives the bundle's data capability.
  */
 export interface PlatformBundleBinders {
+    /** Explicit host selection only; no default payment executor. */
+    payments?: (env: Env) => PaymentServices | null;
     /**
      * The supabase-js `createClient` used by the default Supabase Storage blob binder. Declared
      * structurally here so the composition entry's declarations reference no data-module type.

package/dist/composition/composeBundle.js

@@ -39,6 +39,8 @@ export function createBundleComposer(binders = {}) {
             analytics: binders.analytics?.(capabilities.analytics, env) ?? null,
             transactional: binders.transactional?.(capabilities.transactional, capabilities.data, env) ?? null,
         };
+        if (binders.payments)
+            ports.payments = binders.payments(env);
         ports.scheduler = binders.scheduler?.(capabilities.scheduler, env) ?? null;
         return { id, descriptor, ports };
     };

package/dist/composition/index.js

@@ -1,3 +1,4 @@
+// The existing composer accepts one explicit payments binder; default hosts stay cold.
 export { createBundleComposer, } from "./composeBundle.js";
 export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
 export { createNodeHost, } from "./nodeHost.js";

package/dist/payments/adapterConformance.d.ts

@@ -0,0 +1,8 @@
+import type { PaymentAdapterConformanceEvidence, PaymentAdapterConformanceSubject, PaymentVerifyNormalizePort } from "./contracts/index.js";
+/** Runner-independent adapter proof. Verification fixtures are owned by each adapter. */
+export declare function runPaymentAdapterConformance(subjects: readonly (PaymentAdapterConformanceSubject & {
+    verification: readonly {
+        input: Parameters<PaymentVerifyNormalizePort["verifyAndNormalize"]>[0];
+        expected: Awaited<ReturnType<PaymentVerifyNormalizePort["verifyAndNormalize"]>>;
+    }[];
+})[]): Promise<PaymentAdapterConformanceEvidence>;