@openlup/platform 0.20.0 → 0.22.0

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.22.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0220) before selecting the opt-in M05 parity seams or
+M06 composition bindings, the M07 payment selectors, or M08 fulfillment services. Native delivery alignment stays off or shadow until a host composes its automatic-renewal runner with the G23 admission decorator. 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.22.0` set with the published `0.21.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,11 @@ 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. |
+| `./fulfillment/omnipack` | Opt-in Node fulfillment example with injected I/O; default-off. |
+| `./payments` | Experimental prepared-attempt ordering with injected persistence, execution and failure policy; contracts at `./payments/contracts`. |
+| `./fulfillment`, `./fulfillment/contracts` | [Experimental fulfillment services, contracts and status canon](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#fulfillment-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 +776,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 +1057,187 @@ 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.
+
+### Reference-support surface
+
+The vendor subpaths additionally expose these experimental helpers for the
+reference application's existing host bindings. Each declaration names its exact
+reference consumer and carries `@experimental`: Reference-application support
+surface; may change.
+
+| Entry | Additional exports |
+| --- | --- |
+| `@openlup/platform/payments/stripe` | `createStripeSandboxPaymentExecutionAdapter`, `createStripePaymentReconciliationProvider`, `mapStripeIntent`, `mapSetupIntent`, `normalizeStripeFailureEvidence` |
+| `@openlup/platform/payments/tpay` | `createTpayPaymentExecutionAdapter`, `createTpayPaymentReconciliationProvider`, `createTpayHttpClient`, `normalizeTpayFailureEvidence`, `aliasValue`, `ProviderAttemptPreDispatchError` |
+
+Types are inferred from those functions; no extra type export or neutral payment
+entry is added. These are the existing contributed implementations, including
+rich execution, recovery and filtered audit carriers. The host still owns SDK
+construction, environment/feature flags, callback/return presentation, account
+readiness and simulator composition. Its prepared-attempt facade re-exports the
+same error class so `instanceof` preserves the no-charge trust boundary.
+The M07 factories' neutral envelopes and capability limits remain unchanged;
+reference-support availability establishes no provider activation or stable API.

package/dist/composition/composeBundle.d.ts

@@ -1,7 +1,14 @@
 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 {
+    fulfillment?: {
+        runDispatch(): Promise<unknown>;
+    } | null;
+    payments?: PaymentServices | null;
     http: HttpRuntimePort | null;
     scheduler: SchedulerPort | null;
     blob: BlobStoragePort | null;
@@ -21,6 +28,12 @@ export interface PlatformBundle {
  * transactional binder also receives the bundle's data capability.
  */
 export interface PlatformBundleBinders {
+    /** Explicit host selection only; no default binder. */
+    fulfillment?: (env: Env) => {
+        runDispatch(): Promise<unknown>;
+    } | null;
+    /** 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,10 @@ export function createBundleComposer(binders = {}) {
             analytics: binders.analytics?.(capabilities.analytics, env) ?? null,
             transactional: binders.transactional?.(capabilities.transactional, capabilities.data, env) ?? null,
         };
+        if (binders.fulfillment)
+            ports.fulfillment = binders.fulfillment(env);
+        if (binders.payments)
+            ports.payments = binders.payments(env);
         ports.scheduler = binders.scheduler?.(capabilities.scheduler, env) ?? null;
         return { id, descriptor, ports };
     };

package/dist/composition/fulfillmentContribution.d.ts

@@ -0,0 +1,21 @@
+import type { Contribution, RequiredSchema } from '@openlup/core/readiness';
+/** Structural callables keep composition independent of fulfillment implementation types. */
+export declare function createFulfillmentContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    fulfillment: 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/fulfillmentContribution.js

@@ -0,0 +1,19 @@
+/** Structural callables keep composition independent of fulfillment implementation types. */
+export function createFulfillmentContribution(input) {
+    const contribution = {
+        manifest: {
+            name: '@openlup/platform', version: input.version, kind: 'rail',
+            module: { id: 'fulfillment', kind: 'capability', provides: ['./fulfillment'], dependsOn: [] },
+            emits: [], handles: input.handlers.map(handler => handler.eventType),
+            schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), env: [],
+            requiredPorts: Object.keys(input.fulfillment), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+        },
+        handlers: input.handlers, schedules: input.schedules, routes: input.routes,
+    };
+    return {
+        contributions: [contribution],
+        ports: Object.fromEntries(Object.entries(input.fulfillment).filter(([, fn]) => typeof fn === 'function').map(([name, fn]) => [`@openlup/platform/fulfillment:${name}`, fn])),
+        routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/fulfillment:${route.id}`, route.handle])),
+        triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/fulfillment:${schedule.id}`, schedule.run])),
+    };
+}

package/dist/composition/index.d.ts

@@ -4,3 +4,4 @@ export { createNodeHost, type NodeHost, type NodeHostAdmission, type NodeHostDep
 export { createCatalogContribution, type CatalogContributionInput } from "./catalogContribution.js";
 export { createInventoryContribution } from "./inventoryContribution.js";
 export { createShippingContribution } from "./shippingContribution.js";
+export { createFulfillmentContribution } from "./fulfillmentContribution.js";

package/dist/composition/index.js

@@ -1,6 +1,8 @@
+// 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";
 export { createCatalogContribution } from "./catalogContribution.js";
 export { createInventoryContribution } from "./inventoryContribution.js";
 export { createShippingContribution } from "./shippingContribution.js";
+export { createFulfillmentContribution } from "./fulfillmentContribution.js";

package/dist/fulfillment/adapterConformance.d.ts

@@ -0,0 +1,3 @@
+import type { FulfillmentAdapterConformanceEvidence, FulfillmentAdapterConformanceSubject } from "./contracts/index.js";
+/** Runner-independent offline proof using only adapter-owned fixtures. Throws on a violated contract. */
+export declare function runFulfillmentAdapterConformance(subjects: readonly FulfillmentAdapterConformanceSubject[]): Promise<FulfillmentAdapterConformanceEvidence>;

package/dist/fulfillment/adapterConformance.js

@@ -0,0 +1,223 @@
+import { dispatchEvidence, dispatchResult } from "./dispatchProjection.js";
+import { projectObservation } from "./observationProjection.js";
+import { readFulfillmentCapabilities } from "./providerCapabilities.js";
+import { runFulfillmentDispatchWorker } from "./providerDispatchWorker.js";
+/** Runner-independent offline proof using only adapter-owned fixtures. Throws on a violated contract. */
+export async function runFulfillmentAdapterConformance(subjects) {
+    const evidence = [];
+    const cases = [];
+    for (const subject of subjects) {
+        const { adapter, fixtures } = subject;
+        const caps = adapter.capabilities;
+        const passed = (operation) => { cases.push({ subjectId: subject.subjectId, operation, passed: true }); };
+        requireFact(caps.defaultOff === true, "default-off");
+        requireFact(readFulfillmentCapabilities([caps], null).kind === "refused", "selection_required");
+        const first = fixtures.dispatch[0];
+        requireFact(Boolean(first), "dispatch fixture required");
+        const disabled = readFulfillmentCapabilities([{ ...caps, selected: false }], first.input.selection);
+        requireFact(disabled.kind === "refused" && disabled.refusal.reason === "disabled", "disabled selection");
+        const missing = await adapter.dispatch.prepare({ ...first.input, selection: { ...first.input.selection, providerRef: null } });
+        requireFact(missing.kind === "refused" && missing.refusal.reason === "selection_required", "adapter selection_required");
+        passed("default-off and selection_required");
+        for (const fixture of fixtures.dispatch) {
+            const before = subject.readIoCount();
+            const prepared = await adapter.dispatch.prepare(fixture.input);
+            requireSame(prepared, fixture.expectedPrepare, "prepare fixture");
+            requireFact(subject.readIoCount() === before, "prepare before I/O");
+            assertDurable(prepared, subject);
+            if (prepared.kind === "refused") {
+                passed("dispatch refused before I/O");
+                continue;
+            }
+            requireFact(caps.operations.dispatch.supported, "unsupported dispatch refuses");
+            requireSame(prepared.evidence, dispatchEvidence(prepared.evidence), "prepared evidence allowlist");
+            requireFact(prepared.evidence.providerRef === fixture.input.selection.providerRef, "prepared provider identity");
+            requireSame(prepared.evidence.contactRevision, fixture.input.contactRevision, "prepared contact identity");
+            const mismatch = await adapter.dispatch.dispatch(fixture.input, { ...prepared.evidence, commandFingerprint: `${prepared.evidence.commandFingerprint}:mismatch` });
+            requireSame(mismatch, { kind: "not_dispatched", effectMayHaveSucceeded: false,
+                refusal: { reason: "not_dispatchable", phase: "dispatch", retryable: false } }, "mismatched preparation refusal");
+            requireFact(subject.readIoCount() === before, "mismatch before I/O");
+            requireFact(fixture.expectedDispatch !== undefined, "dispatch expected result");
+            const result = await adapter.dispatch.dispatch(fixture.input, prepared.evidence);
+            requireSame(result, fixture.expectedDispatch, "dispatch fixture");
+            requireSame(result, dispatchResult(result), "dispatch allowlist");
+            assertDurable(result, subject);
+            if (result.kind === "accepted") {
+                requireSame(result.evidence, prepared.evidence, "dispatch fingerprint identity");
+                requireFact(result.externalRef.length > 0 && result.providerAttemptKey.length > 0 && result.labelKey.length > 0, "accepted proof before local ACK");
+            }
+            else
+                requireFact(result.kind === "unknown" ? result.effectMayHaveSucceeded : !result.effectMayHaveSucceeded, "unknown versus refused");
+            if (fixture.replay) {
+                const calls = subject.readIoCount();
+                requireSame(await adapter.dispatch.dispatch(fixture.input, prepared.evidence), result, "dispatch replay");
+                requireFact(subject.readIoCount() === calls, "replay no second I/O");
+            }
+            passed(`dispatch ${result.kind}, fingerprint, mismatch and replay`);
+        }
+        for (const operation of ["create", "read", "void"]) {
+            const supported = caps.operations[operation === "create" ? "labelCreate" : operation === "read" ? "labelRead" : "labelVoid"].supported;
+            const rows = fixtures.label?.[operation] ?? [];
+            if (supported)
+                requireFact(Boolean(adapter.label) && rows.length > 0, `label ${operation} fixture`);
+            if (rows.length)
+                requireFact(Boolean(adapter.label), "label port required");
+            for (const fixture of rows) {
+                const before = subject.readIoCount();
+                const result = operation === "create" ? await adapter.label.create(fixture.input[0])
+                    : operation === "read" ? await adapter.label.read(fixture.input[0])
+                        : await adapter.label.void(fixture.input[0]);
+                requireSame(result, fixture.expected, `label ${operation}`);
+                if (!supported && !(operation === "read" && caps.labelReadOwner === "host_storage")) {
+                    requireFact("refusal" in result && result.refusal?.reason === "unsupported", `unsupported label ${operation}`);
+                    requireFact(subject.readIoCount() === before, "unsupported label before I/O");
+                }
+                if (!(operation === "read" && "kind" in result && result.kind === "available"))
+                    assertDurable(result, subject);
+                passed(`label ${operation}`);
+            }
+        }
+        if (caps.operations.verifyObservation.supported)
+            requireFact(Boolean(adapter.observation) && Boolean(fixtures.observation?.length), "observation fixtures required");
+        const events = new Map();
+        for (const fixture of fixtures.observation ?? []) {
+            requireFact(Boolean(adapter.observation), "observation port required");
+            const result = await adapter.observation.verifyAndNormalize(...fixture.input);
+            requireSame(result, fixture.expected, "observation fixture");
+            assertDurable(result, subject);
+            if (!caps.operations.verifyObservation.supported)
+                requireFact(result.kind === "refused" && result.refusal.reason === "unsupported", "unsupported observation");
+            if (result.kind === "verified") {
+                requireSame(result.observation, projectObservation(result.observation), "observation allowlist");
+                const observation = result.observation;
+                const identity = stable({ provider: observation.fact.providerKind, reference: observation.fact.fulfillmentReference,
+                    kind: observation.eventKind, outcome: observation.fact.canonicalStatus, occurredAt: observation.fact.occurredAt });
+                const previous = events.get(observation.eventKey);
+                if (previous)
+                    requireFact(previous.identity === identity, "eventKey includes outcome and occurrence");
+                events.set(observation.eventKey, { identity, occurredAt: observation.fact.occurredAt });
+                const replay = await adapter.observation.verifyAndNormalize(...fixture.input);
+                requireSame(replay, result, "observation exact retry");
+            }
+            passed("observation identity, replay and redaction");
+        }
+        if (caps.operations.readback.supported)
+            requireFact(Boolean(adapter.readback) && Boolean(fixtures.readback?.length), "readback fixtures required");
+        for (const fixture of fixtures.readback ?? []) {
+            requireFact(Boolean(adapter.readback), "readback port required");
+            const result = await adapter.readback.read(...fixture.input);
+            requireSame(result, fixture.expected, "readback fixture");
+            assertDurable(result, subject);
+            if (!caps.operations.readback.supported)
+                requireFact(result.kind === "unsupported", "unsupported readback");
+            if (fixture.localMissing)
+                requireFact(result.kind === "unknown" && result.refusal.reason === "local_missing", "local missing is never absence");
+            if (result.kind === "absent") {
+                requireFact(caps.operations.exactAbsence.supported, "unsupported exact absence refuses");
+                const { mode: _mode, ...scope } = fixture.input[0];
+                requireSame(result.scope, scope, "absence scope");
+                requireFact(result.proof.kind === "authoritative_exact_lookup" && /^evidence:.+/.test(result.proof.evidenceRef) && Number.isFinite(Date.parse(result.proof.checkedAt)), "absence proof");
+            }
+            if (result.kind === "found")
+                requireFact(result.externalRef === fixture.input[0].externalRef || fixture.input[0].externalRef === null, "found identity");
+            passed(`readback ${result.kind}`);
+        }
+        for (const name of ["stockSync", "productSync"]) {
+            const supported = caps.operations[name === "stockSync" ? "syncStock" : "syncProducts"].supported;
+            const port = adapter[name];
+            const rows = fixtures[name] ?? [];
+            if (supported)
+                requireFact(Boolean(port) && rows.length > 0, `${name} fixtures required`);
+            for (const fixture of rows) {
+                requireFact(Boolean(port), `${name} port required`);
+                let returned;
+                try {
+                    // Dispatch a typed fixture tuple to its adapter-owned operation.
+                    const method = port[fixture.operation];
+                    returned = await method.apply(port, fixture.input);
+                }
+                catch (error) {
+                    const refusal = error;
+                    requireFact(refusal.reason === "unsupported" && refusal.phase === "sync" && refusal.retryable === false, "typed unsupported sync refusal");
+                    returned = { kind: "refused", refusal };
+                }
+                requireSame(returned, fixture.expected, `${name} ${fixture.operation}`);
+                assertDurable(returned, subject);
+                if (!supported)
+                    requireFact(typeof returned === "object" && returned !== null && "kind" in returned && returned.kind === "refused", "unsupported sync");
+                passed(`${name} ${fixture.operation}`);
+            }
+        }
+        if (subject.store) {
+            await checkStore(subject);
+            passed("store G14 replay, own-key remap and one-remap bound");
+        }
+        assertDurable({ subjectId: subject.subjectId, providerRef: caps.providerRef }, subject);
+        evidence.push({ subjectId: subject.subjectId, providerRef: caps.providerRef });
+    }
+    return { subjects: evidence, cases };
+}
+async function checkStore(subject) {
+    const fixture = subject.store;
+    const store = await fixture.create();
+    const first = await store.claim(fixture.claim);
+    requireFact(first.kind === "claimed", "store initial claim");
+    const replay = await store.claim(fixture.claim);
+    requireFact(replay.kind === "claimed" && replay.record.replayed, "store same-key claim replay");
+    const attempt = () => store.recordProviderAttempt(fixture.mappedAttemptKey, fixture.claim.fulfillmentRef, fixture.claim.evidence, fixture.claim.mode, "recorded");
+    requireFact(!(await attempt()).replayed && (await attempt()).replayed, "G14 same key replays");
+    requireFact(fixture.mappedAttemptKey !== fixture.remappedAttemptKey, "G14 remap own key");
+    requireFact(fixture.claim.requestKey === fixture.remappedClaim.requestKey && fixture.claim.evidence.commandFingerprint !== fixture.remappedClaim.evidence.commandFingerprint, "draft remap fixture");
+    const remap = await store.claim(fixture.remappedClaim);
+    requireFact(remap.kind === "claimed", "draft re-claim");
+    const row = await store.read(fixture.claim.requestKey);
+    requireSame(row?.evidence, fixture.remappedClaim.evidence, "atomic remap fingerprint and evidence");
+    assertDurable(row, subject);
+    requireFact(!(await store.recordProviderAttempt(fixture.remappedAttemptKey, fixture.claim.fulfillmentRef, fixture.remappedClaim.evidence, fixture.claim.mode, "recorded")).replayed, "G14 new mapped attempt");
+    const attempts = await store.readMappedAttempts();
+    requireFact(attempts.length === 2, "G14 no duplicate durable attempts");
+    requireSame(attempts.map(row => row.attemptKey).sort(), [fixture.mappedAttemptKey, fixture.remappedAttemptKey].sort(), "G14 durable remap identity");
+    for (const attempt of attempts) {
+        requireSame(attempt.preparedEvidence, dispatchEvidence(attempt.preparedEvidence), "G14 sanitized evidence only");
+        assertDurable(attempt, subject);
+    }
+    const stale = await store.begin({ dispatchRef: row.dispatchRef, commandFingerprint: fixture.claim.evidence.commandFingerprint });
+    requireFact(stale.kind === "refused", "stale prepared command refuses");
+    let claims = 0;
+    let calls = 0;
+    let reads = 0;
+    const bounded = await runFulfillmentDispatchWorker({
+        store: { ...await fixture.create(), async read() { return null; }, async readCandidate() { reads += 1; return reads === 1 ? fixture.request : fixture.remappedRequest; },
+            async claim() { claims += 1; return { kind: "refused", refusal: { reason: "contact_stale", phase: "claim", retryable: true } }; } },
+        provider: { prepare: request => subject.adapter.dispatch.prepare(request), async dispatch() { calls += 1; throw new Error("unexpected dispatch"); } },
+        listCandidates: async () => [fixture.request], config: { mode: "stage", batchLimit: 1 },
+        keys: { request: () => fixture.claim.requestKey, mappedAttempt: (_key, index) => index === 0 ? fixture.mappedAttemptKey : fixture.remappedAttemptKey,
+            acceptance: () => ({ providerAttemptKey: "fixture-attempt", labelKey: "fixture-label" }) },
+    });
+    requireFact(claims === 2 && calls === 0 && !bounded.ok, "one-remap limit before I/O");
+}
+function assertDurable(value, subject) {
+    const text = JSON.stringify(value) ?? "";
+    requireFact(!subject.sensitiveValues.filter(Boolean).some(secret => text.includes(secret) || text.includes(JSON.stringify(secret).slice(1, -1))), "durable secret redaction");
+    const visit = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            requireFact(!/^(rawBody|rawPayload|rawCommand|password|secret|credential|authorization|headers|signedUrl)$/i.test(key), "durable field allowlist");
+            if (typeof child === "string")
+                requireFact(!/[?&](?:signature|sig|token|x-amz-signature|credential)=/i.test(child), "durable signed URL");
+            visit(child);
+        }
+    };
+    visit(value);
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => `${JSON.stringify(key)}:${stable(child)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function requireSame(actual, expected, label) { requireFact(stable(actual) === stable(expected), label); }
+function requireFact(value, label) { if (!value)
+    throw new Error(`fulfillment_adapter_conformance:${label}`); }

package/dist/fulfillment/bindings.d.ts

@@ -0,0 +1,3 @@
+import type { FulfillmentServices, FulfillmentServicesOptions } from './contracts/index.js';
+/** Explicit selection; no environment readers, implicit provider or automatic dispatch. */
+export declare function createFulfillmentServices(options: FulfillmentServicesOptions): FulfillmentServices;

package/dist/fulfillment/bindings.js

@@ -0,0 +1,29 @@
+import { FULFILLMENT_NATIVE_UNSUPPORTED } from './nativeUnsupported.js';
+import { readFulfillmentCapabilities } from './providerCapabilities.js';
+import { runFulfillmentDispatchWorker } from './providerDispatchWorker.js';
+/** Explicit selection; no environment readers, implicit provider or automatic dispatch. */
+export function createFulfillmentServices(options) {
+    const { enabled, selection, capability, store, provider, readiness: observe, listCandidates, now } = options;
+    const config = { ...options.config }, keys = { ...options.keys };
+    const readiness = async () => {
+        if (enabled !== true)
+            return { ready: false, refusal: { reason: 'disabled', phase: 'selection', retryable: false } };
+        const selected = readFulfillmentCapabilities(capability ? [capability] : [], selection);
+        if (selected.kind === 'refused')
+            return { ready: false, refusal: selected.refusal };
+        if (!selected.descriptor.operations.dispatch.supported)
+            return { ready: false, refusal: { reason: 'unsupported', phase: 'selection', retryable: false } };
+        if (!store || !provider)
+            return { ready: false, refusal: FULFILLMENT_NATIVE_UNSUPPORTED };
+        return observe();
+    };
+    return {
+        readiness,
+        async runDispatch() {
+            const state = await readiness();
+            if (!state.ready)
+                return 'kind' in state.refusal ? state.refusal : { kind: 'refused', refusal: state.refusal };
+            return runFulfillmentDispatchWorker({ store: store, provider, listCandidates, keys, config, now });
+        },
+    };
+}