@openlup/platform 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -10,6 +10,216 @@ in the source repository.
 
 ## [Unreleased]
 
+## [0.22.0]
+
+- Publishable on the npm `latest` dist-tag as `0.22.0`, from tag
+  `openlup-platform-v0.22.0`.
+
+- Add eleven experimental reference-application support exports on the existing payment vendor subpaths. Reuse contributed execution, readback, mapping and diagnostic helpers; preserve the no-charge error class identity. Neutral payment exports and default activation remain unchanged.
+
+Migration: none.
+
+### Opt-in warehouse fulfillment example
+
+Add the experimental, opt-in warehouse fulfillment entry described in the README behind the frozen neutral fulfillment ports: explicit injected I/O, prepared-byte binding, closed evidence, token observations and positive readback. Default-off; account readiness is host-owned. Exact absence, label create/void and cancellation remain unsupported.
+
+Missing or malformed evidence refuses before credential resolution or HTTP.
+
+Migration: none
+
+### Offline warehouse fulfillment conformance
+
+Prove the opt-in warehouse fulfillment entry described in the README with M08's offline conformance runner using injected
+HTTP and synthetic fixtures. Cover dispatch replay and refusals, observation,
+readback, stock and product sync, plus real-worker host-ledger fences after
+restart and retention eviction. No provider-account or activation proof is claimed.
+
+Migration: none
+
+### Fulfillment contracts and status canon
+
+Add experimental `fulfillment` and type-only `fulfillment/contracts` entries with
+contributed status decisions, strict core parser bindings, concrete provider/store
+ports and injected default-off capabilities. No adapter, executor, route or default
+profile is activated; existing reference integrations remain unchanged.
+
+Declared adaptation: empty or absent provider selection is a typed refusal in the
+new package, rather than the donor host's implicit simulator alias. The donor alias
+remains an open owner follow-up; this contribution does not change donor logic.
+Private provider trace columns and registry/environment values are excluded from
+the neutral package; persisted command fingerprints and opaque host keys are retained.
+
+Migration: none (new surface; no existing reference behavior changes).
+
+### Fulfillment paid handoff and fenced dispatch
+
+Add the paid outbox handler/recovery classifier, injected dispatch worker and
+separate durable command-ledger protocol through the new fulfillment entry.
+Preserve one contact remap, opaque host keys, actual-command fingerprints,
+readback/attempt/begin order and local accepted-proof repair without another POST.
+Provider/money/inventory authority remains injected; no SQL, route or activation.
+
+Approved port amendment G14 adds recordProviderAttempt to the new
+FulfillmentStorePort. It records only sanitized prepared DispatchEvidence plus
+mode/recorded status and opaque references, after authoritative claim readback;
+same-key replay writes no second attempt and contact remap retains its own key.
+No new named export or subpath is added by this method. Other contracts are unchanged.
+
+Correctable draft re-claim must refresh fingerprint and evidence atomically.
+Store conformance and native durability/fencing and SQL proofs remain later work.
+
+Migration: none (new surface; contracts and orchestration land in one release).
+
+### Fulfillment observation and sync workers
+
+Add neutral observation effects, verified ingress, observation reconciliation,
+tracking, stock/product sync, read-only evidence handlers and the offline
+runFulfillmentAdapterConformance at the existing fulfillment entry.
+
+Migration: approved G15 extends the unreleased SyncCursor with optional
+coverageGapSkus (legacy absence reads as []). Only consecutive succeeded runs
+confirm a reservation coverage gap; running/failed cursors clear the set.
+Migration: approved G16 changes readLocalInventoryStock(requestedAt) to typed
+unaggregated lines with skuRef, quantity balances, fulfillable, locationStatus,
+lotStatus and expiresAt. The worker filters/sums at the captured clock; expiry
+exactly then is excluded. Inventory authority and the provider stock-sync shape
+are unchanged.
+Migration: approved G17 adds inline localPersistence: ingress records eventKey
+receipts preserving firstReceivedAt and marks processing idempotently;
+reconciliation reads local status/latestStatusOccurredAt/handedOverAt. No named
+persistence type is exported. Durable replay and processing remain host obligations.
+A superseding conflict returns superseded but persists only processed status,
+without a dedicated superseded-reason field.
+
+Correlated ingress requires a nonblank observation or dispatch external reference
+before acceptance/status/effects/processed mark; failure leaves the receipt
+unprocessed. Stock-contention annotation is best-effort before the original stock
+failure is rethrown; recovered-picked receipt diagnostics remain typed. Effects
+retain stock → handover → tracking → invoice and callback/throw order.
+Reconciliation fails the run on unknown readback and projects unmapped correlation
+evidence before host calls. Product evidence reads retain safe authorization/read
+refusal detail. Private codecs, keys, carrier URLs and provider errors stay
+host-owned; typed evidence replaces raw payload pass-through. The conformance
+runner accepts adapter-owned offline subjects and returns sanitized evidence;
+fixture checks do not establish durable store atomicity or arrival alignment.
+
+### Fulfillment native persistence and delivery alignment
+
+Add native shipment, evidence, stock, recovery, dispatch, paid-handoff and
+alignment stores through the existing fulfillment entry. Sparse migration
+projections bind native units 5/27/51/73/74; install the complete catalogue.
+Coverage-gap cursor state and received/status/processed evidence are
+durable, while local inventory lines and contact preparation remain explicit
+host inputs. Native 3pl acceptance uses a dispatch evidence receipt and preserves
+the cancellation fence without inventing an owned label or physical packing.
+
+Native admission: overdue-delivery admission guards only NEW cycle
+admission/insert, matching the donor's guard_cycle_insert. Existing-cycle retries
+through renewal operations and dunning bypass admission and neither mint nor
+consume a one-use receipt. No retry_scheduled state or payments lifecycle change is
+introduced. Native continuity requires the complete canonical migration graph,
+real-PostgreSQL installation, replay and access-control checks.
+
+### Fulfillment operator lifecycle and customer delay projection
+
+Add host-owned operator and replacement handlers through the fulfillment entry.
+Mutation callbacks require actor attribution and idempotency keys; the host owns
+atomic replay receipts and replacement eligibility, reservation and hold effects.
+Native bindings return a shared typed unsupported refusal without writing.
+Customer delay projection keeps absent cases distinct, hides aligned history
+when the schedule advances and never presents manual review as protection.
+Label helpers preserve transient downloads and cleanup uncertainty. Current
+parcel helpers retain sequence selection and companion attribution. These
+exports mount no route, dispatch no parcel and attest no replacement arrival.
+
+### Fulfillment commerce reads and recorded progress
+
+Add host-owned commerce list/detail projections, a shipments overview handler and
+typed read callbacks. Projected payment status passes through unchanged and
+native reads return the shared unsupported refusal. Preserve opaque host overview
+buckets and the legacy shipment-status facade. Progress completion requires
+recorded milestones and uses the host-resolved customer step.
+
+### Fulfillment internal simplification
+
+Reuse the empty stock-balance constructor in aggregation and sync, and append to
+private recovery groups without copying each growing array. Fulfillment results,
+public contracts, key bytes and effect order remain unchanged.
+
+### Fulfillment service composition and preparation
+
+Add explicit default-off fulfillment services, a structural contribution and an
+inert reference preparation binding. Authoritative source edits and redacted
+context synchronization share the native dispatch and shipment locks. Missing
+preparation refuses readiness. No route, schedule, renewal wrapper or automatic
+dispatch is activated.
+
+### Fulfillment presentation ownership
+
+The status canon, actual-evidence tracking progress, current-parcel selection and
+canonical fact parsers belong to `@openlup/core/fulfillment`. Platform keeps thin
+compatibility re-exports and preserves its existing narrowed fact type names.
+Fulfillment contracts re-export the shared status and progress types from core.
+Server orchestration remains in platform. Browser code, including the host
+status, fact and current-parcel facades and the account order views, imports
+these helpers from core, so no browser graph loads the platform fulfillment
+runtime.
+
+Migration: existing platform imports remain valid; no application or schema
+migration is required. Core exposes narrowed fact aliases with a `Canonical`
+prefix while its generic fact exports retain their names.
+
+Migration: upgrade core, outbox and platform together from `0.21.0` to `0.22.0` for exact peer pins. Install the complete canonical native migration chain through units 73/74 (`20261022080000_fulfillment_command_ledger.sql` and `20261022090000_fulfillment_delivery_alignment.sql`), never the sparse package projections alone. Before, these fulfillment services were host-owned; after, explicitly compose selected ports and default-off services. Nothing mounts routes, schedules dispatch or composes the native renewal runner automatically. Keep native alignment off or shadow until the G23 decorator is composed. Arrival alignment remains once and later-only; undelivered replacements remain outstanding, and replacement confirmation must only record actual customer arrival. Preserve G15–G17 cursor, receipt and local-status persistence when implementing host stores. An application rollback does not reverse the forward migrations; older runners refuse the extended ledger.
+
+### 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.
+
+- Native delivery alignment stays off or shadow until a host composes the native automatic-renewal runner with the G23 renewal admission decorator. The decorator alone neither composes nor activates the runner.
+- The core fulfillment status map carries localized adopter labels; replace them with host-injected labels or internationalization keys before any stable-framework claim.
+- The warehouse adapter example is opt-in and has offline conformance only; no provider-account proof or activation is established. Exact absence, label create/void and cancellation remain unsupported.
+- After an alignment extension, a deferred renewal operation at the old schedule remains claimed with no reader or reservation effect. Changed terms snapshots conflict under the existing snapshot-conflict rules.
+
+Native parity remains host-owned at these seams. Missing native bindings use the shared `FULFILLMENT_NATIVE_UNSUPPORTED` refusal; no partial write or parity claim is implied.
+
+| Amendment | Host-owned seam and native boundary |
+| --- | --- |
+| G18 | Replacement creation and atomic eligibility/replay receipts; native replacement callback refuses. |
+| G19 | Operator mutations, actor attribution and replay receipts; native mutation callbacks refuse. |
+| G20 | Customer alignment rows; native reader refuses, while the pure delay projection remains callable. |
+| G21 | Commerce list/detail and shipments overview; native read callbacks refuse. |
+| G22 | Authoritative preparation edits, authorization and replay receipts; missing preparation binding refuses before dispatch, after disabled/selection/readiness checks. |
+
 ## [0.21.0]
 
 - Publishable on the npm `latest` dist-tag as `0.21.0`, from tag
@@ -167,50 +377,3 @@ projections as an installation chain.
   `canonicalAddressKey` retains a locale-specific character fold. M16 owns their
   move behind a host-supplied market pack with a canonical-key migration plan.
 - Reference shipping UI copy remains locale-specific until M16.
-
-## [0.19.0]
-
-- Publishable on the npm `latest` dist-tag as `0.19.0`, from tag
-  `openlup-platform-v0.19.0`.
-
-### 0.18.0 → 0.19.0 set scope
-
-- Prepare the complete development-preview minor set at `0.19.0`, including everything on main since `0.18.0`; core and outbox are unchanged republications, and UI stays private `0.0.0`.
-- M05 parity adds opt-in shipping-promise consent, post-discount threshold shipping and acquisition orchestration to the experimental pricing, promotions and shipping entries; financial policy and acquisition capability remain host supplied.
-- M05 parity adds effective native bundle selection and an authoritative preview hook, optional resolved-target/detail/feed context fields and `selectEffectiveBundleTargetPrice`; effective feeds require unambiguous gross unit anchors and whole-BOM readiness.
-- Add `createConcurrentCommercePriceAuthorityPort` with concurrent history scheduling, selected-list identity and base-refusal precedence; browser additions are type-only.
-- Catalog/contracts draft canonical JSON detects lone surrogates without regex lookbehind so it loads in Safari before 16.4, with unchanged behavior.
-- M06 P5a adds explicit inventory store/provider bindings and structural inventory contribution, keeping reference catalog-stock composition inert and managed authorization intact; native new-purchase stock reads remain unsupported pending an owner decision and native adjustment still refuses.
-- M06 P5a retains focused installed-consumer, runtime-role, managed FEFO/adjustment and consume/refund replay evidence with unproved parity gates retained in the M06 ledger.
-- M06 P5b adds opt-in shipping selection, address and flat-rate bindings with injected validation and authority; native address writes remain unsupported and refuse required readiness.
-- M06 P5b adds the final isolated installed inventory/shipping consumer, preserving incumbent selection errors and flat-rate behavior.
-- M06 in progress: inventory and shipping entries are early surfaces; module not complete
-- Supporting main changes sort platform registration lists one item per line and use the database clock in the M05 P7 quote witness; neither adds runtime behavior.
-
-Migration: upgrade the complete `@openlup/*` set from `0.18.0` to `0.19.0` for exact internal pins; existing bindings need no change and new module adoption remains explicit and experimental. Hosts selecting shipping promises must forward `shippingTerms` through both acceptance callbacks and use a context schema that preserves the selected terms. Bind `resolveQuoteShippingPromotions` to the promotions factory to select the bounded two-pass threshold path; financial policy and acquisition capability remain host supplied. The additive APIs require a minor set and introduce no activation. For both M05 24b and M06 P5b, the pricing and promotions API reports reorder existing enum/union members because declaration emit order changed (24b follows the catalog-to-pricing import); no member is added, removed or changed and callers need no migration for that reorder. Install the complete canonical migration catalogue, never sparse package projections as an installation chain; this preparation adds no SQL migration.
-
-### 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 remains closed for M05 mounted admin/feed readback with an injected stock reader, while native new-purchase stock reads remain unsupported despite P5a's installed native inventory-store read proof.
-- 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.
-- M05 parity seams are opt-in and omitted bindings preserve incumbent defaults, outputs, read order, scheduling, refusals, acceptance-token bytes and exported SQL.
-- Native inventory adjustment remains unsupported; native address writes and flat-rate saves refuse required-capability readiness.
-- M06 managed host ATP/forecast/supply/pagination, remaining compensation/concurrency/lock-order, exact-prefix upgrade/ledger, address idempotency/conflict/readback and runtime rate authority remain pending in the M06 ledger.
-- M06 adopter stock-wait lifecycle, durable subscription timing and staging control observations retain their separate C5/C6 evidence gates.
-
-### Size note
-
-Only platform `pack.docs.maxPackedBytes` rises from 40,960 to 49,152 B; all other caps and budgets remain unchanged. All three baselines use integrity-verified published `0.18.0` tarballs.
-
-Question (2026-10-21): "The platform package's root docs (README + CHANGELOG) will exceed their 40,960 B gzip cap at the next release. What should we do?"
-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.

package/README.md

@@ -4,12 +4,12 @@ Development preview. This package is part of the publishable set with core and o
 
 It holds the runnable server substrate an OpenLup application composes: the Node HTTP runtime, BFF dispatch, scheduling and job leases, blob storage, data gateways, the node-postgres migration runner and bundle composition. Ports and their contracts stay in `@openlup/core/platform-runtime`.
 
-For the prepared `0.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
+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.21.0` set with the published `0.20.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.
 
@@ -34,7 +34,9 @@ or provider-account certification.
 | `./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 |
@@ -1218,3 +1220,24 @@ 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

@@ -5,6 +5,9 @@ interface PaymentServices {
 }
 type Env = Record<string, string | undefined>;
 export interface PlatformBundlePorts {
+    fulfillment?: {
+        runDispatch(): Promise<unknown>;
+    } | null;
     payments?: PaymentServices | null;
     http: HttpRuntimePort | null;
     scheduler: SchedulerPort | null;
@@ -25,6 +28,10 @@ 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;
     /**

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.fulfillment)
+            ports.fulfillment = binders.fulfillment(env);
         if (binders.payments)
             ports.payments = binders.payments(env);
         ports.scheduler = binders.scheduler?.(capabilities.scheduler, env) ?? null;

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

@@ -5,3 +5,4 @@ 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>;