@openlup/platform 0.19.0 → 0.21.0

package/README.md

@@ -1,19 +1,21 @@
 # @openlup/platform
 
-Development preview. This package joins core and outbox in the publishable set from the next set version; this configuration does not establish a registry release or a stable API. Its repository-directory publish command refuses publication; the authorized package-release workflow owns publication.
+Development preview. This package is part of the publishable set with core and outbox; preparation does not establish a registry release or a stable API. Its repository-directory publish command refuses publication; the authorized package-release workflow owns publication.
 
 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.19.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0190) before selecting the opt-in M05 parity seams or
-M06 composition bindings. M06 in progress: inventory and shipping entries are early surfaces; module not complete
-The size gate compares this candidate with the published `0.18.0` tarball;
+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.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 |
 | --- | --- |
@@ -30,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 |
@@ -37,13 +42,19 @@ or provider-account certification.
 | `./pricing/contracts` | Dependency-free authority, money, quote and offer DTOs and version constants |
 | `./promotions` | Experimental promotion application, admin handlers, native read/sweep, SQL projections and acceptance |
 | `./promotions/contracts` | Dependency-free preview and admin DTOs |
-| `./shipping` | Experimental delivery ports, injected-schema handlers, summary and evidence |
+| `./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 |
 
 ## Shipping
 
 Shipping handlers require injected host schemas; contracts are type-only with opaque provider/carrier strings.
 No vendor code, inventory import, activation or parity claim.
+Native flat-rate save requires the rate port, a ready Core report and
+`nativeRateSchema`, a same-database Core `SchemaObservation` proving the applied
+seed identity and settings objects. A candidate schema label is not proof;
+later forwards do not invalidate an applied seed. The reference host exposes
+`observeNativeRateSchema()` for this ledger/object observation and retains
+caller-declared schema requirements. Missing proof keeps the named refusal.
 
 ## Inventory
 
@@ -763,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
@@ -1044,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>;

package/dist/payments/adapterConformance.js

@@ -0,0 +1,109 @@
+import { projectVerifiedEvidence } from "./verifiedEvidenceProjection.js";
+import { validatePaymentExecutionContractResult } from "@openlup/core/testing";
+/** Runner-independent adapter proof. Verification fixtures are owned by each adapter. */
+export async function runPaymentAdapterConformance(subjects) {
+    const observations = [];
+    const cases = [];
+    for (const subject of subjects) {
+        const { adapter, executionInput, readbackInput } = subject;
+        const provider = adapter.capabilities.providerKind;
+        requireFact(executionInput.money.currency.length > 0, "configured currency");
+        adapter.attemptPort.validateInput(executionInput);
+        const result = await adapter.attemptPort.execute(executionInput);
+        const { handoff, ...execution } = result;
+        const sensitiveValues = [executionInput.payer?.email, executionInput.payer?.name, executionInput.customerAuthorization,
+            handoff?.kind === "client-confirmed" ? handoff.payload : handoff?.url].filter((v) => v !== undefined && v.length > 0);
+        const sensitiveForms = sensitiveValues.flatMap(value => [value, JSON.stringify(value).slice(1, -1)]);
+        const payerForms = [executionInput.payer?.email, executionInput.payer?.name]
+            .filter((value) => Boolean(value?.length))
+            .flatMap(value => [value, JSON.stringify(value).slice(1, -1)]);
+        const input = {
+            idempotencyKey: executionInput.attemptRef, providerIdempotencyKey: executionInput.providerIdempotencyKey,
+            providerRequestFingerprint: executionInput.fingerprint, paymentIntentId: executionInput.intentRef,
+            amountMinor: executionInput.money.amountMinor, currency: executionInput.money.currency, mode: "one_time",
+        };
+        const validation = validatePaymentExecutionContractResult({ input, expectedProvider: provider, sensitiveValues: sensitiveForms,
+            result: { provider, providerAttemptId: result.dispatch.kind === "dispatched" ? result.dispatch.providerPaymentRef : null,
+                providerSessionId: null, attemptStatus: result.outcome.kind === "attempt" ? result.outcome.status : "processing",
+                nextActionKind: null, requestPayload: { providerIdempotencyKey: input.providerIdempotencyKey,
+                    providerRequestFingerprint: input.providerRequestFingerprint }, responsePayload: result.diagnostics },
+        });
+        requireFact(validation.ok, "execution diagnostics and taxonomy");
+        requireFact(!payerForms.some(value => JSON.stringify(result).includes(value)), "execution payer redaction");
+        if (adapter.capabilities.payerContext.requiresPayerBlock && !executionInput.payer) {
+            requireFact(result.dispatch.kind === "notDispatched" && result.dispatch.evidence.exact
+                && result.dispatch.evidence.phase === "before-dispatch", "missing required input exact notDispatched");
+        }
+        const returned = await adapter.readbackPort.readPayment(readbackInput);
+        const { handoff: readbackHandoff, ...readback } = "handoff" in returned ? returned : { ...returned, handoff: undefined };
+        requireFact(!sensitiveForms.some(value => JSON.stringify(readback).includes(value)), "readback secret redaction");
+        requireFact(sameIdentity(readback.identity, readbackInput.identity) && sameMoney(readback.expectedMoney, readbackInput.expectedMoney), "readback exact identity and money");
+        requireFact(adapter.capabilities.readback === "supported" ? returned.kind !== "unsupported" : returned.kind === "unsupported", "readback capability");
+        if ("observedMoney" in returned)
+            requireFact(sameMoney(returned.observedMoney, readbackInput.expectedMoney), "observed money");
+        if (adapter.capabilities.close === "supported") {
+            requireFact(typeof adapter.readbackPort.close === "function", "close method present");
+            const closed = await adapter.readbackPort.close(readbackInput);
+            requireFact(closed.kind !== "unsupported" && sameIdentity(closed.identity, readbackInput.identity)
+                && sameMoney(closed.expectedMoney, readbackInput.expectedMoney), "close exact identity and money");
+        }
+        else if (adapter.readbackPort.close) {
+            requireFact((await adapter.readbackPort.close(readbackInput)).kind === "unsupported", "close refuses");
+        }
+        let absence;
+        if (adapter.capabilities.exactAbsence === "supported")
+            requireFact(adapter.absencePort !== undefined, "absence port present");
+        if (adapter.absencePort) {
+            requireFact(subject.absenceInput !== undefined, "absence input present");
+            absence = await adapter.absencePort.proveAbsence(subject.absenceInput);
+            requireFact(sameIdentity(absence.identity, subject.absenceInput.identity)
+                && sameMoney(absence.expectedMoney, subject.absenceInput.expectedMoney), "absence exact identity and money");
+            requireFact(adapter.capabilities.exactAbsence === "supported" ? absence.kind !== "unsupported" : absence.kind === "unsupported", "absence capability");
+            if (absence.kind === "absent")
+                requireFact(absence.evidence.exact && absence.evidence.complete
+                    && absence.evidence.lookupReference.trim().length > 0, "complete absence evidence");
+        }
+        const fingerprints = new Map();
+        const moneyEvents = [];
+        for (const fixture of subject.verification) {
+            const verified = await adapter.verifyPort.verifyAndNormalize(fixture.input);
+            requireFact(JSON.stringify(verified) === JSON.stringify(fixture.expected), "verified fixture");
+            if (verified.kind !== "refusal") {
+                requireFact(verified.kind !== "money" || (verified.money !== null
+                    && Number.isSafeInteger(verified.money.amountMinor) && verified.money.amountMinor > 0
+                    && verified.money.currency.trim().length > 0)
+                    || (verified.outcome !== "succeeded" && verified.outcome !== "refunded" && verified.outcome !== "disputed"), "settling outcome requires positive money");
+                requireFact(!sensitiveForms.some(value => JSON.stringify({ payload: projectVerifiedEvidence(verified, fixture.input, "require-evidence").rawPayload, diagnostics: result.diagnostics }).includes(value)), "audit payload secret redaction");
+                const outcome = verified.kind + ":" + verified.outcome;
+                const previous = fingerprints.get(verified.providerEventId);
+                if (previous)
+                    requireFact(previous.outcome === outcome && previous.fingerprint === verified.fingerprint, "replay identity fingerprint");
+                if (verified.kind === "money") {
+                    for (const event of moneyEvents) {
+                        if (event.reference === verified.providerPaymentRef && event.outcome !== outcome) {
+                            requireFact(event.eventId !== verified.providerEventId && event.fingerprint !== verified.fingerprint, "changing outcome identity");
+                        }
+                    }
+                    moneyEvents.push({ reference: verified.providerPaymentRef, outcome, eventId: verified.providerEventId, fingerprint: verified.fingerprint });
+                }
+                fingerprints.set(verified.providerEventId, { fingerprint: verified.fingerprint, outcome });
+            }
+        }
+        // Transient handoffs are deliberately excluded from the returned evidence.
+        void readbackHandoff;
+        observations.push({ subjectId: subject.subjectId, execution, readback, ...(absence ? { absence } : {}) });
+        cases.push({ subjectIds: [subject.subjectId], name: "execution, verification, capability and exact readback", passed: true });
+    }
+    return { subjects: observations, cases };
+}
+function requireFact(value, label) {
+    if (!value)
+        throw new Error(`payment_adapter_conformance:${label}`);
+}
+function sameMoney(left, right) {
+    return left.amountMinor === right.amountMinor && left.currency === right.currency;
+}
+function sameIdentity(left, right) {
+    return left.provider === right.provider && left.providerPaymentRef === right.providerPaymentRef
+        && left.intentRef === right.intentRef && left.attemptRef === right.attemptRef;
+}

package/dist/payments/bindings.d.ts

@@ -0,0 +1,3 @@
+import type { PaymentServices, PaymentServicesOptions } from "./contracts/repair.js";
+/** One host-owned scope per runtime unit; no driver or environment discovery. */
+export declare function createPaymentServices(options: PaymentServicesOptions): PaymentServices | null;

package/dist/payments/bindings.js

@@ -0,0 +1,17 @@
+/** One host-owned scope per runtime unit; no driver or environment discovery. */
+export function createPaymentServices(options) {
+    if (options.schema?.truth !== "supported" || !options.openTruth)
+        return null;
+    const openTruth = options.openTruth;
+    return {
+        async run(work) {
+            const scope = await openTruth();
+            try {
+                return await work(scope.port);
+            }
+            finally {
+                await scope.close();
+            }
+        },
+    };
+}

package/dist/payments/checkoutActivePaymentActionResolver.d.ts

@@ -0,0 +1,7 @@
+import type { CheckoutActivePaymentActionResolver, CheckoutActionReadProvider } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort } from "./contracts/reconciliation.js";
+export declare function createCheckoutActivePaymentActionResolver(deps: {
+    readPort: PaymentVerifyReadPort;
+    providers: Partial<Record<string, CheckoutActionReadProvider>>;
+    railHandoffKinds(rail: string): readonly ("redirect" | "client-confirmed")[];
+}): CheckoutActivePaymentActionResolver;

package/dist/payments/checkoutActivePaymentActionResolver.js

@@ -0,0 +1,77 @@
+import { toClaimedAttemptShape } from "./paymentVerifyNowService.js";
+const LIVE_INTENT_STATUSES = new Set(["requires_action", "processing"]);
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing"]);
+export function createCheckoutActivePaymentActionResolver(deps) {
+    return {
+        async readActiveAction(authority) {
+            try {
+                const initial = await deps.readPort.readVerifiableAttempt({
+                    orderId: authority.orderId,
+                    paymentIntentId: authority.paymentIntentId,
+                });
+                if (!matchesAuthority(initial, authority) || !isLive(initial))
+                    return null;
+                const provider = deps.providers[authority.executionRail];
+                const providerPaymentId = provider?.resolvePaymentReference(initial) ?? null;
+                if (!provider || !providerPaymentId)
+                    return null;
+                const attempt = toClaimedAttemptShape(initial, providerPaymentId);
+                const reading = await provider.readRecoveryPayment({
+                    providerPaymentId,
+                    attempt,
+                    purpose: "active_checkout",
+                });
+                if (!reading.clientAction
+                    || !actionMatchesRail(reading.clientAction, authority.executionRail, deps.railHandoffKinds)
+                    || reading.manualReviewRequired
+                    || !reading.identityMatches
+                    || !reading.configuredMoneyMatches
+                    || reading.status.status !== "pending")
+                    return null;
+                const current = await deps.readPort.readVerifiableAttempt({
+                    orderId: authority.orderId,
+                    paymentIntentId: authority.paymentIntentId,
+                });
+                if (!sameCanonicalAttempt(initial, current) || !isLive(current))
+                    return null;
+                return reading.clientAction;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function matchesAuthority(snapshot, authority) {
+    return Boolean(snapshot)
+        && snapshot?.orderId === authority.orderId
+        && snapshot.orderClientId === authority.clientId
+        && snapshot.paymentIntentId === authority.paymentIntentId
+        && snapshot.paymentAttemptId === authority.paymentAttemptId
+        && snapshot.provider === authority.executionRail;
+}
+function isLive(snapshot) {
+    return Boolean(snapshot)
+        && LIVE_INTENT_STATUSES.has(snapshot?.intentStatus ?? "")
+        && LIVE_ATTEMPT_STATUSES.has(snapshot?.attemptStatus ?? "");
+}
+function actionMatchesRail(action, rail, railHandoffKinds) {
+    return action.provider === rail && railHandoffKinds(rail).includes(action.kind);
+}
+function sameCanonicalAttempt(before, after) {
+    return Boolean(after)
+        && after?.orderId === before.orderId
+        && after.orderClientId === before.orderClientId
+        && after.paymentIntentId === before.paymentIntentId
+        && after.paymentAttemptId === before.paymentAttemptId
+        && after.paymentId === before.paymentId
+        && after.provider === before.provider
+        && after.providerAttemptId === before.providerAttemptId
+        && after.providerSessionId === before.providerSessionId
+        && after.intentProviderPaymentId === before.intentProviderPaymentId
+        && after.intentStatus === before.intentStatus
+        && after.attemptStatus === before.attemptStatus
+        && after.amountMinor === before.amountMinor
+        && after.currency.toUpperCase() === before.currency.toUpperCase()
+        && after.localUpdatedAt === before.localUpdatedAt;
+}

package/dist/payments/checkoutRecoveryPaymentResolver.d.ts

@@ -0,0 +1,8 @@
+import type { CheckoutRecoveryPaymentResolver, PaymentProviderRecoveryProvider } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort, PaymentProviderReconciliationPort } from "./contracts/reconciliation.js";
+export declare function createCheckoutRecoveryPaymentResolver(deps: {
+    readPort: PaymentVerifyReadPort;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderRecoveryProvider>>;
+    now?: () => Date;
+}): CheckoutRecoveryPaymentResolver;

package/dist/payments/checkoutRecoveryPaymentResolver.js

@@ -0,0 +1,87 @@
+import { terminalAmountMismatch } from "./paymentProviderReconciliationEvidence.js";
+import { toClaimedAttemptShape, verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing", "created"]);
+export function createCheckoutRecoveryPaymentResolver(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        async resolve(input) {
+            if (!input.paymentIntentId)
+                return { kind: "retry_new" };
+            const snapshot = await deps.readPort.readVerifiableAttempt({
+                orderId: input.orderId,
+                paymentIntentId: input.paymentIntentId,
+            });
+            if (!snapshot) {
+                return input.intentStatus === "created" || input.intentStatus === "failed"
+                    ? { kind: "retry_new" }
+                    : { kind: "awaiting_provider" };
+            }
+            return resolveSnapshot(snapshot, deps, now);
+        },
+    };
+}
+async function resolveSnapshot(snapshot, deps, now) {
+    if (snapshot.attemptStatus === "succeeded" || snapshot.intentStatus === "succeeded") {
+        return { kind: "paid" };
+    }
+    if (snapshot.attemptStatus === "failed" || snapshot.intentStatus === "failed") {
+        return { kind: "retry_new" };
+    }
+    if (!LIVE_ATTEMPT_STATUSES.has(snapshot.attemptStatus)) {
+        return { kind: "awaiting_provider" };
+    }
+    const provider = deps.providers[snapshot.provider];
+    const providerPaymentId = provider?.resolvePaymentReference(snapshot) ?? null;
+    if (!provider || !providerPaymentId)
+        return { kind: "awaiting_provider" };
+    const attempt = toClaimedAttemptShape(snapshot, providerPaymentId);
+    try {
+        // Every caller of this resolver is a buyer holding a recovery link open, so
+        // an intent still waiting for its first payment method is one they can be
+        // handed back — not one to close under them and replace.
+        const recovery = await provider.readRecoveryPayment({
+            providerPaymentId,
+            attempt,
+            purpose: "active_checkout",
+        });
+        if (recovery.manualReviewRequired
+            || !recovery.identityMatches
+            || !recovery.configuredMoneyMatches) {
+            return { kind: "manual_review" };
+        }
+        if (recovery.clientAction) {
+            return { kind: "resume_existing", clientAction: recovery.clientAction };
+        }
+        if (recovery.status.status === "pending" || recovery.status.status === "unknown") {
+            return { kind: "awaiting_provider" };
+        }
+        if (terminalAmountMismatch(attempt, recovery.status)) {
+            return { kind: "manual_review" };
+        }
+        const verified = await verifyPaymentAttemptNow({
+            snapshot,
+            applyPort: deps.applyPort,
+            providers: deps.providers,
+            providerPaymentId,
+            providerStatus: recovery.status,
+            now,
+        });
+        if (verified.status !== "succeeded" && verified.status !== "failed") {
+            return { kind: "awaiting_provider" };
+        }
+        const current = await deps.readPort.readVerifiableAttempt({
+            orderId: snapshot.orderId,
+            paymentIntentId: snapshot.paymentIntentId,
+        });
+        if (current?.attemptStatus === "succeeded" || current?.intentStatus === "succeeded") {
+            return { kind: "paid" };
+        }
+        if (current?.attemptStatus === "failed" || current?.intentStatus === "failed") {
+            return { kind: "retry_new" };
+        }
+        return verified.status === "succeeded" ? { kind: "paid" } : { kind: "retry_new" };
+    }
+    catch {
+        return { kind: "awaiting_provider" };
+    }
+}