@openlup/platform 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -8,6 +8,105 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.20.0]
+
+- Publishable on the npm `latest` dist-tag as `0.20.0`, from tag
+  `openlup-platform-v0.20.0`.
+
+- Refresh release size-gate baselines from the published `0.19.0` tarballs; all caps remain unchanged.
+
+- Keep active subscriptions active on portable dunning exhaustion (invariant repair).
+
+Migration: apply the complete portable catalogue through
+`20261021120000_dunning_lifecycle_active_repair.sql` at position 71. Previously,
+NULL next retry expired the case and paused an active subscription; it now leaves
+the case open and repairable, retains the final notice and exhaustion event, and
+changes no subscription or cycle dates. Existing rows are not rewritten. Pass
+NULL only when `isDunningLadderExhausted` holds; a class-terminated rung-one refusal
+still must not be passed as NULL. There is no managed twin yet; the managed
+baseline still needs a separate forward.
+
+- Add the readiness-gated native flat-rate binding; the host supplies the named
+  role-free lane and fixed-key rate port, as in the reference composition.
+- Require the native port and Core readiness for the shipping seed migration.
+- Refuse missing-row saves; native audit remains explicitly unsupported and best effort.
+
+Migration:
+Apply the complete portable chain through 20261021200000_shipping_flat_rate_seed.
+The seed preserves an existing rate and inserts zero only when absent; no ACL or
+role changes are made. New code on an unmigrated schema keeps refusing. Older code
+reads the seeded zero as it read an absent row. An application rollback does not reverse either forward
+(positions 71 and 72), and older runners refuse the extended ledger.
+Managed host-save authority remains pending.
+
+- Add the shipping `SHIPPING_MIGRATIONS` export and the optional
+  `nativeRateReadiness` / `nativeRateSchema` binding dependencies.
+
+Migration: upgrade the complete `@openlup/*` set from `0.19.0` to `0.20.0`
+for exact internal pins. Native rate bindings require the selected port plus
+Core readiness and a same-database schema observation of the applied seed.
+Install the complete canonical migration catalogue, never sparse package
+projections as an installation chain.
+
+### Cumulative M06 status
+
+- M06 remains incomplete: inventory and shipping are development-preview
+  surfaces, with managed-host proof classes pending.
+- Inventory and shipping contracts, stock/ATP reads, reserve/release/expire
+  operations, subscription forecasts, delivery selection, address and flat-rate
+  handlers first shipped in `0.18.0`. Opt-in inventory/shipping/composition
+  bindings (P5a/P5b) first shipped in `0.19.0`. M06's only new behaviour in
+  `0.20.0` is native flat-rate save behind readiness; the portable dunning
+  invariant repair is separate from M06. Host-owned policy and unsupported
+  operations retain their explicit boundaries.
+
+### Known limitations
+
+- The portable dunning invariant repair has no managed twin in this set. The
+  managed baseline pauses active subscriptions on exhaustion; keeping them active
+  requires a separate managed forward. Portable proof does not establish managed parity.
+
+- 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 refuse
+  required-capability readiness. Native flat-rate save is supported only behind
+  the selected port, Core readiness and applied-seed schema observation.
+- Native new-purchase stock read is deferred to the native-backend parity round
+  (owner 2026-10-21), second after M05 bundle-1; required readiness still refuses
+  honestly.
+- Native shipping-rate save has no durable audit: audit is explicitly unsupported,
+  and the incumbent handler swallows the best-effort audit failure.
+- Native flat-rate value bounds (integer, 0 <= value <= the host request schema's
+  maximum) are enforced by that schema, not a database CHECK; the reference
+  maximum is 100,000 minor units.
+- Managed host ATP/forecast/dated-supply/pagination readback is not proved and
+  remains pending in the M06 ledger; no managed-host parity is claimed.
+- Managed two-session lock order/concurrency and uncovered compensation paths
+  are not proved on a managed host and remain pending; no equivalence is claimed.
+- Managed exact-prefix upgrade/ledger is not proved on a managed host and remains
+  pending; no managed installation equivalence is claimed.
+- Managed address adapter idempotency/conflict/readback is not proved on a managed
+  host and remains pending; no fixture-to-host equivalence is claimed.
+- Managed successful flat-rate read/save remains pending host authority and is
+  not proved on a managed host; no successful managed host-save claim is made.
+- M06 adopter stock-wait lifecycle, durable subscription timing and staging
+  control observations retain their separate C5/C6 evidence gates. Busy/try-gate
+  protocol, durable stock-wait continuity and staging flag/TTL rows transferred
+  to C5 adopter evidence are dispositions, not PASS.
+- Shipping contracts retain national-registry address fields and
+  `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

package/README.md

@@ -1,13 +1,15 @@
 # @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.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
+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;
 preparation, offline adapter evidence and a passing size cap grant no publication
 or provider-account certification.
 
@@ -37,13 +39,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
 

package/dist/shipping/bindings.d.ts

@@ -1,3 +1,4 @@
+import type { ReadinessReport, SchemaObservation } from "@openlup/core/readiness";
 import type { BffResponder } from "../bff/index.js";
 import type { CustomerAddressBookPort, CustomerAddressMutationPort, CustomerAddressesDeps } from "./addressPorts.js";
 import type { CustomerAddressSchemas } from "./addressSchemas.js";
@@ -16,6 +17,10 @@ type Store = {
 export interface ShippingBindingDependencies {
     dataKind: string;
     createManagedStore?: () => Store | null;
+    /** Core report for the selected shipping contribution, observed by the host. */
+    nativeRateReadiness?: ReadinessReport;
+    /** Same-database Core observation of the applied shipping seed and required objects. */
+    nativeRateSchema?: SchemaObservation;
     nativeStore?: Omit<Store, "addressMutationPort"> | null;
     responder: BffResponder;
     selection?: {

package/dist/shipping/bindings.js

@@ -5,7 +5,17 @@ import { createDeliveryOptionsHandler, createPickupPointSearchHandler, createPic
 export function createShippingBindings(deps) {
     const native = deps.dataKind === "postgres";
     const addressWrites = native ? "shipping_native_address_writes_unsupported" : null;
-    const flatRateSave = native ? "shipping_native_flat_rate_save_unsupported" : null;
+    const nativeRateReady = typeof deps.nativeStore?.shippingRateDataPort?.getShippingFlatMinor === "function"
+        && typeof deps.nativeStore?.shippingRateDataPort?.setShippingFlatMinor === "function"
+        && typeof deps.nativeStore?.shippingRateDataPort?.recordPromotionAudit === "function"
+        && deps.nativeRateReadiness?.state === "ready"
+        && typeof deps.nativeRateReadiness.candidate?.database === "string"
+        && deps.nativeRateReadiness.candidate.database.length > 0
+        && deps.nativeRateSchema?.database === deps.nativeRateReadiness.candidate.database
+        && deps.nativeRateSchema.version === "20261021200000_shipping_flat_rate_seed"
+        && ["public.commerce_settings", "public.commerce_settings.value_minor", "public.commerce_settings.updated_at"].every(name => deps.nativeRateSchema?.objects?.some(entry => entry.present === true && entry.object?.name === name
+            && entry.object.kind === (name === "public.commerce_settings" ? "table" : "column")));
+    const flatRateSave = native && !nativeRateReady ? "shipping_native_flat_rate_save_unsupported" : null;
     const refused = (reason) => ({
         store: {}, handlers: { options: null, search: null, validate: null, addresses: null, rate: null },
         readiness: { ready: false, reason }, unsupported: { addressWrites, flatRateSave },
@@ -14,7 +24,7 @@ export function createShippingBindings(deps) {
         return refused("shipping_store_incompatible");
     if (native && deps.addresses?.requireWrites)
         return refused(addressWrites);
-    if (native && deps.rate)
+    if (native && deps.rate && flatRateSave)
         return refused(flatRateSave);
     const selected = native ? deps.nativeStore : deps.createManagedStore?.();
     if ((deps.addresses || deps.rate) && !selected)

package/dist/shipping/index.d.ts

@@ -18,3 +18,17 @@ export type { AdminShippingRateHandlerDeps, ShippingRateDataPort, ShippingRateHa
 export { createShippingBindings, type ShippingBindingDependencies, type ShippingBindings } from "./bindings.js";
 export type { ShippingTerms, ShippingPolicyEntry, ShippingPolicy, ShippingSettings } from "./contracts/threshold.js";
 export { shippingTermsSchema, shippingPolicySchema, parseShippingTerms, hasShippingTerms, normalizeShippingPolicy, resolveShippingPolicy, resolveThresholdShipping } from "./thresholdPolicy.js";
+/** Sparse canonical projections, never an install chain. */
+export declare const SHIPPING_MIGRATIONS: readonly [{
+    readonly id: "20260807140000_read_parity_catalog";
+    readonly catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql";
+    readonly position: 1;
+    readonly sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea";
+    readonly url: URL;
+}, {
+    readonly id: "20261021200000_shipping_flat_rate_seed";
+    readonly catalogPath: "db/platform/migrations/20261021200000_shipping_flat_rate_seed.sql";
+    readonly position: 72;
+    readonly sha256: "34f8696f515a2cc072395db5a3de2d9b09643d13236ee3851d0d78123f907eae";
+    readonly url: URL;
+}];

package/dist/shipping/index.js

@@ -8,3 +8,8 @@ export { readAddresses, readOrdererProfiles, addressUsedByActiveSubscription, ad
 export { createAdminShippingRateHandler } from "./adminShippingRateHandler.js";
 export { createShippingBindings } from "./bindings.js";
 export { shippingTermsSchema, shippingPolicySchema, parseShippingTerms, hasShippingTerms, normalizeShippingPolicy, resolveShippingPolicy, resolveThresholdShipping } from "./thresholdPolicy.js";
+/** Sparse canonical projections, never an install chain. */
+export const SHIPPING_MIGRATIONS = [
+    { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+    { id: "20261021200000_shipping_flat_rate_seed", catalogPath: "db/platform/migrations/20261021200000_shipping_flat_rate_seed.sql", position: 72, sha256: "34f8696f515a2cc072395db5a3de2d9b09643d13236ee3851d0d78123f907eae", url: new URL("../../sql/20261021200000_shipping_flat_rate_seed.sql", import.meta.url) },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.19.0",
+    "@openlup/core": "0.20.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"

package/release-gates.json

@@ -370,8 +370,8 @@
     "maxUnpackedBytes": 5734400,
     "maxFiles": 2100,
     "baseline": {
-      "version": "0.18.0",
-      "packedBytes": 779849
+      "version": "0.19.0",
+      "packedBytes": 805872
     },
     "browserEntries": {
       "./catalog/contracts": 4096,

package/sql/20261021200000_shipping_flat_rate_seed.sql

@@ -0,0 +1 @@
+INSERT INTO public.commerce_settings (key, value_minor) VALUES ('shipping_flat_minor', 0) ON CONFLICT (key) DO NOTHING;

package/src/shipping/bindings.ts

@@ -1,3 +1,4 @@
+import type { ReadinessReport, SchemaObservation } from "@openlup/core/readiness";
 import type { BffResponder } from "../bff/index.js";
 import type { CustomerAddressBookPort, CustomerAddressMutationPort, CustomerAddressesDeps } from "./addressPorts.js";
 import type { CustomerAddressSchemas } from "./addressSchemas.js";
@@ -17,6 +18,10 @@ type Store = {
 export interface ShippingBindingDependencies {
   dataKind: string;
   createManagedStore?: () => Store | null;
+  /** Core report for the selected shipping contribution, observed by the host. */
+  nativeRateReadiness?: ReadinessReport;
+  /** Same-database Core observation of the applied shipping seed and required objects. */
+  nativeRateSchema?: SchemaObservation;
   nativeStore?: Omit<Store, "addressMutationPort"> | null;
   responder: BffResponder;
   selection?: { port: DeliverySelectionPort; searchPort: PickupPointSearchPort; schemas: DeliverySelectionSchemas };
@@ -40,14 +45,25 @@ export interface ShippingBindings {
 export function createShippingBindings(deps: ShippingBindingDependencies): ShippingBindings {
   const native = deps.dataKind === "postgres";
   const addressWrites = native ? "shipping_native_address_writes_unsupported" : null;
-  const flatRateSave = native ? "shipping_native_flat_rate_save_unsupported" : null;
+  const nativeRateReady = typeof deps.nativeStore?.shippingRateDataPort?.getShippingFlatMinor === "function"
+    && typeof deps.nativeStore?.shippingRateDataPort?.setShippingFlatMinor === "function"
+    && typeof deps.nativeStore?.shippingRateDataPort?.recordPromotionAudit === "function"
+    && deps.nativeRateReadiness?.state === "ready"
+    && typeof deps.nativeRateReadiness.candidate?.database === "string"
+    && deps.nativeRateReadiness.candidate.database.length > 0
+    && deps.nativeRateSchema?.database === deps.nativeRateReadiness.candidate.database
+    && deps.nativeRateSchema.version === "20261021200000_shipping_flat_rate_seed"
+    && ["public.commerce_settings", "public.commerce_settings.value_minor", "public.commerce_settings.updated_at"].every(name =>
+      deps.nativeRateSchema?.objects?.some(entry => entry.present === true && entry.object?.name === name
+        && entry.object.kind === (name === "public.commerce_settings" ? "table" : "column")));
+  const flatRateSave = native && !nativeRateReady ? "shipping_native_flat_rate_save_unsupported" : null;
   const refused = (reason: string): ShippingBindings => ({
     store: {}, handlers: { options: null, search: null, validate: null, addresses: null, rate: null },
     readiness: { ready: false, reason }, unsupported: { addressWrites, flatRateSave },
   });
   if (!native && deps.dataKind !== "supabase") return refused("shipping_store_incompatible");
   if (native && deps.addresses?.requireWrites) return refused(addressWrites!);
-  if (native && deps.rate) return refused(flatRateSave!);
+  if (native && deps.rate && flatRateSave) return refused(flatRateSave);
   const selected: Store | null | undefined = native ? deps.nativeStore : deps.createManagedStore?.();
   if ((deps.addresses || deps.rate) && !selected) return refused("shipping_store_required");
   // Native address mutations remain unavailable even if an untyped host plants a writer.

package/src/shipping/index.ts

@@ -24,3 +24,9 @@ export type { AdminShippingRateHandlerDeps, ShippingRateDataPort, ShippingRateHa
 export { createShippingBindings, type ShippingBindingDependencies, type ShippingBindings } from "./bindings.js";
 export type { ShippingTerms, ShippingPolicyEntry, ShippingPolicy, ShippingSettings } from "./contracts/threshold.js";
 export { shippingTermsSchema, shippingPolicySchema, parseShippingTerms, hasShippingTerms, normalizeShippingPolicy, resolveShippingPolicy, resolveThresholdShipping } from "./thresholdPolicy.js";
+
+/** Sparse canonical projections, never an install chain. */
+export const SHIPPING_MIGRATIONS = [
+  { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+  { id: "20261021200000_shipping_flat_rate_seed", catalogPath: "db/platform/migrations/20261021200000_shipping_flat_rate_seed.sql", position: 72, sha256: "34f8696f515a2cc072395db5a3de2d9b09643d13236ee3851d0d78123f907eae", url: new URL("../../sql/20261021200000_shipping_flat_rate_seed.sql", import.meta.url) },
+] as const;